Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.riftmap.dev/llms.txt

Use this file to discover all available pages before exploring further.

The Riftmap API uses workspace API keys for all programmatic access. Keys are scoped to a single workspace, bypass role checks (they’re owner‑equivalent within their workspace), and never require a workspace_id parameter.

​
Create a key

In the app:
  1. Pick the workspace from the user menu.
  2. Navigate to Settings → API keys.
  3. Click Create new key, give it a label (e.g. claude-code-laptop, ci-staging), and copy the raw key.
The plaintext key is shown once at creation time. After that, only the SHA‑256 hash and a short prefix (rfm_live_xxxx…) are stored. If you lose it, revoke the old key and mint a new one. A workspace can have multiple keys — best practice is one per environment or per agent, so revocation is granular.

​
Header conventions

Riftmap accepts the API key on either of two headers. Use whichever is more natural for your client.

​
Canonical: X-API-Key

curl "https://riftmap.dev/api/v1/repositories/lookup?url=https://github.com/myorg/repo" \
  -H "X-API-Key: rfm_live_xxx"

​
Convenience alias: Authorization: Bearer

The Authorization header is checked only when the value starts with rfm_ — this avoids collision with user JWTs that share the same header in browser sessions. 
curl "https://riftmap.dev/api/v1/repositories/lookup?url=https://github.com/myorg/repo" \
  -H "Authorization: Bearer rfm_live_xxx"

​
Priority order

Within a single request the server checks, in order: X-API-Key → Authorization: Bearer rfm_* → session cookie → 401. Mixing two methods is fine; the first to match wins.

​
401 body

{
  "detail": "Authentication required. Provide X-API-Key, Authorization: Bearer <key>, or log in."
}

​
Cross‑workspace isolation

Every authenticated response is scoped to the workspace that owns the API key. Attempts to reach another workspace’s resources return 404, not 403 — we deliberately don’t leak whether the resource exists.

​
Rate limits

SurfaceLimitNotes
Read endpointsGenerous (no per-request cap today)GET /repositories, GET /context, GET /impact, GET /graph, etc. Subject to change as usage grows.
Authenticated mutations (POST / PUT / PATCH / DELETE)60 / minute per keyKeyed by API key prefix. Configurable via RATELIMIT_AUTHENTICATED_MUTATIONS.
On limit exceeded, the response is 429 with { "detail": "...", "retry_after": N } and a Retry-After: N header. Both Retry-After and X-Request-ID are exposed via CORS, so browser fetch() can read them directly.

​
Revoking a key

DELETE /workspaces/{id}/api-keys/{key_id} — or click the trash icon in Settings → API keys. Revocation is immediate; subsequent requests with the revoked key return 401.

​
Storing keys safely

  • Do not check API keys into git. Treat them like any other production secret.
  • Do not ship them in client‑side bundles — workspace keys are owner‑equivalent within their workspace and must stay server‑side.
  • For local development against the production API, use a .env.local file (or your shell’s secret manager) and reference the key as RIFTMAP_API_KEY.