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
secretthat’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:
400with a validation message.
Next: Creating schedules — cron, recurrence text, and the one-call composite.