Skip to main content

Authentication

The public OpenDocs API is hosted at:

https://api.opendocs.cc

Every non-public endpoint accepts either of two auth schemes: an API key in the Authorization header (preferred for CLI, agents, and backend integrations) or a browser session cookie (used by the dashboard). Exceptions are noted on each endpoint's reference page.

API key authentication​

API keys are prefixed with:

od_live_

Send the key as a bearer token:

curl https://api.opendocs.cc/api/v1/me \
  -H "Authorization: Bearer od_live_xxxxx"

Keys are long-lived. The plaintext is only ever returned at creation time — save it immediately, because the dashboard and API only ever show a redacted preview afterwards. See API keys for creating, listing, and revoking keys programmatically.

Session authentication​

Some endpoints — workspace management, team and invitation flows, profile and avatar uploads — only accept session auth because they're specifically dashboard surfaces. Calling them with an API key returns 401 unauthorized. Those endpoints are marked "session only" on their reference pages.

Required headers​

For JSON requests with an API key:

Authorization: Bearer od_live_xxxxx
Content-Type: application/json

Getting a key​

  1. Sign up at opendocs.cc/signup.
  2. Complete onboarding (pick a username, then a workspace name + slug).
  3. Open Dashboard → API Keys.
  4. Create a key and copy the plaintext — it won't be shown again.

Or, programmatically after session auth: POST /api/v1/api-keys — see API keys.

CLI browser login​

The CLI also supports a browser-assisted flow:

opendocs login --browser

This opens OpenDocs in the browser and uses the existing web session when one is available. The approval screen shows the signed-in account and workspace so the user can avoid authorizing the wrong account. After approval, the CLI receives a short-lived one-time code on 127.0.0.1, exchanges it with OpenDocs, and stores a normal od_live_ API key locally.

The API key is never placed in the browser redirect URL. Only a one-time code is sent to the local callback, and it must be exchanged with the CLI's verifier before it expires. Agents, CI, and SSH/headless environments should still use OPENDOCS_API_KEY or opendocs login --key.

Common auth failure​

If the key is missing, revoked, or malformed — or the session cookie is expired — the API returns:

{
  "error": "unauthorized"
}

Status 401. If the caller is authenticated but not a member of the workspace in question (or lacks the required role), the status is 403 with error: "forbidden" instead.

Rate limits​

All routes sit behind per-route-group rate limiters — general traffic, publish, batch publish, exports, batch exports. See Errors and pagination for the buckets.