Skip to content

API keys

Personal access tokens (PATs) authenticate every request to the Ritual MCP server. The CLI mints one for you automatically during ritual init; you can also create them manually from your account settings.

Where PATs come from

SourceWhen
ritual init (CLI)Auto-minted on first run. Named Ritual CLI — <hostname>. Stored at ~/.config/ritual/credentials.json and registered as the Bearer token in each coding agent’s MCP config.
Manual creationhttps://app.ritualapp.cloud/settings/tokens → Create token. Use when you’re building your own MCP client, or scripting against the API outside the CLI.

Most users never need to create a PAT manually — ritual init handles it.

Format

PATs are issued as ritual_pat_… (followed by ~32 base32 characters). They’re long-lived (~1 year by default) and tied to your user account, scoped to the workspaces you have access to.

Treat them like passwords — they grant the same access you have in the web UI.

Create a PAT manually

  1. Sign in to app.ritualapp.cloud
  2. Open Settings → Tokens (also reachable via your profile menu → API tokens)
  3. Click Create token
  4. Name it after the surface it’ll live on (e.g. cursor-on-laptop, ci-pipeline)
  5. Copy the token immediately — it is not shown again

Use a PAT

Pass as a Bearer token in the Authorization header on every request to the MCP server:

POST /mcp HTTP/1.1
Host: mcp.ritualapp.cloud
Authorization: Bearer ritual_pat_…
Content-Type: application/json
Accept: application/json, text/event-stream

See the MCP server reference for the full transport details.

Rotate or revoke

In Settings → Tokens:

  • Revoke an existing token to invalidate it immediately. In-flight requests using it will start failing on the next call.
  • Create a new token with the same name + scope, update the consuming surface (CLI: re-run ritual init; manual integration: update the Bearer header), then revoke the old one.

Plan rotations during low-traffic windows — there’s no overlap period where both tokens are valid against the same agent connection.

Storage rules

  • Never commit PATs to git. The CLI stores yours at ~/.config/ritual/credentials.json with 0o600 permissions (owner read/write only).
  • Never paste PATs into chat, screenshots, or shared documents. If a PAT leaks, revoke it immediately, then mint a new one.
  • Don’t share PATs across people. Each PAT is tied to a single user account; an action taken with someone else’s PAT shows up as their action in the audit log.
  • CI / shared infrastructure: create a service-account user, mint that account’s PAT, store in your secrets manager. Don’t use a human user’s PAT for shared CI.

Scopes

Today PATs inherit the full set of permissions of the issuing user (same access you have in the web UI). Per-token scope restrictions (read-only, write-only, single-workspace) are on the roadmap.

Troubleshooting

SymptomLikely causeFix
401 UnauthorizedWrong / revoked PAT, or missing the Bearer prefixVerify the Authorization header is exactly Bearer ritual_pat_… (note the space). Confirm the PAT hasn’t been revoked.
403 ForbiddenPAT is valid but doesn’t have access to the requested workspaceSign in to the web UI as the same account and confirm you can see the workspace there.
406 Not AcceptableClient didn’t send the dual Accept: application/json, text/event-stream header MCP Streamable HTTP requiresSee MCP server FAQ — the spec requires both Accept types.