DOCS · GETTING STARTED

Authentication

Session auth for the dashboard, X-API-Key for integrations, agent keys for MCP and A2A — who can touch what.

Recurrence Cloud has three authentication modes, one per audience. Pick the right one and tenant isolation follows automatically.

1. Session auth — the dashboard

Browser sign-in via Better Auth issues an HTTP-only session cookie. Routes under /api/* (outside /api/v1) expect it: Apps, Webhooks, Schedules, Events, Activity, Billing, MCP servers. Role-based access applies per member — owner, admin (full), dev (create/edit), viewer (read).

2. API keys — integrations & scripts

Keys are created per app, optionally scoped to an environment, with optional expiry:

curl -X POST https://api.recurrence.cloud/api/api-keys \
  -H "Content-Type: application/json" \
  -d '{ "name": "prod-worker", "appId": "<app id>", "expiresAt": "2026-12-31T00:00:00Z" }'

The response contains rawKey exactly once:

{ "id": "…", "keyPrefix": "rc_1a2b", "rawKey": "rc_live_…", "expiresAt": "2026-12-31T00:00:00Z" }

Use it on the programmatic surface as a header — never in URLs:

curl https://api.recurrence.cloud/api/v1/schedules -X POST \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" -d '{ … }'

Rules of the road:

  • Keys are stored as verifiable hashes — they cannot be recovered, only re-created.
  • A compromised key can be deleted (invalid immediately) and replaced; the app token concept means there’s also a webhook-level secret that’s separate from the key — see deliveries.
  • Scope keys by environment (environmentId) so an agent or CI job touches only production or testing.

3. Agent keys — MCP, A2A, UCP

Agent protocol endpoints accept Authorization: Bearer <key> or X-API-Key: <key> — the same app API keys work. Every tools/call is audited (GET /api/activity/agent-activity records key, tool, arguments, outcome), and tenant scoping is enforced in the shared executor: an agent sees only its own organization.

curl -X POST https://api.recurrence.cloud/api/mcp \
  -H "Authorization: Bearer $AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'

What each mode can reach

Surface Auth Audience
/api/v1/* programmatic routes X-API-Key Your code
/api/apps, /api/webhooks, /api/schedules, /api/events, /api/mcp-servers Session cookie Dashboard / server-side with session
/api/billing/*, /api/activity Session cookie Dashboard
/api/mcp, /api/a2a, /api/ucp Bearer or X-API-Key AI agents
/.well-known/agent-card.json, /.well-known/ucp.json None (public) Discovery

Error behavior

  • Missing or invalid key: 401 {"error": "Missing X-API-Key header"} / {"error": "Invalid or expired API key"}.
  • Wrong role: 403.
  • Malformed body: 400 with a validation message.

Next: Creating schedules — cron, recurrence text, and the one-call composite.