Every /api/v2/ request authenticates. The OpenAPI security schemes on each operation are extractApiKey, bearerAuth, and (for the browser app) cookieAuth.
Organization API key
- Sign in at abacusdocs.com.
- Open API (
/api/) or Settings, then manage keys at /api/keys/.
- Create a key. Copy it immediately — the secret is shown once.
- Send it on every request:
One active key per organization. Creating a new one replaces the previous. DELETE on /api/keys/ revokes it. The key is the organization’s credential: it keeps working if the person who minted it leaves, until someone revokes it.
Store the secret in an environment variable or a secrets manager. A leaked key can read and write that organization’s documents, batches, and schemas.
Auth0 access token
The web app and the Black Hole desktop agent send an Auth0 JWT the same way (Authorization: Bearer <jwt>). Use this when the caller is a user, not an org automation.
Session cookie
cookieAuth is the Django sessionid from a browser login. The SPA can call /api/v2 with cookies. Integrations should not.
Surfaces that refuse a key
A key authenticates and can still be refused (403) on routes that answer about the human, not the organization:
GET /api/v2/me/ — profile of the signed-in user- Notification list / mark-read
- Direct-share accept / decline / remove-acceptance
POST …/attachments/kb/ — copies the user’s knowledge-base files; keys are refused outright
The OpenAPI security list still shows extractApiKey on those operations (spectacular lists authenticators, not the permission). Treat 403 as expected for a key, not as a bad token.
Ingest (Black Hole)
/api/v2/ingest/* is Auth0-only. API keys return 403 auth0_required. The organization must be on the allowlist or every route 404s. Agents also need a minimum version (426) and ingest:read / ingest:write scopes.
Auth failures
