> ## Documentation Index
> Fetch the complete documentation index at: https://help.abacusdocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Abacus Docs API Authentication Guide and Key Management

> Learn how to generate, secure, and rotate Abacus Docs API keys, and authenticate every REST API request with the Bearer token scheme.

Every `/api/v2/` request authenticates. The OpenAPI security schemes on each operation are `extractApiKey`, `bearerAuth`, and (for the browser app) `cookieAuth`.

## Organization API key

1. Sign in at [abacusdocs.com](https://abacusdocs.com).
2. Open **API** (`/api/`) or **Settings**, then manage keys at `/api/keys/`.
3. Create a key. Copy it immediately — the secret is shown **once**.
4. Send it on every request:

```text theme={null}
Authorization: Bearer sk-abacus-…
```

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.

<Warning>
  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.
</Warning>

<CodeGroup>
  ```bash cURL theme={null}
  curl https://abacusdocs.com/api/v2/me/ \
    -H "Authorization: Bearer $ABACUS_API_KEY"
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.get(
      "https://abacusdocs.com/api/v2/me/",
      headers={"Authorization": f"Bearer {os.environ['ABACUS_API_KEY']}"},
  )
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://abacusdocs.com/api/v2/me/", {
    headers: { Authorization: `Bearer ${process.env.ABACUS_API_KEY}` },
  });
  console.log(await response.json());
  ```
</CodeGroup>

## 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

| Status  | Meaning                                                                                                    |
| ------- | ---------------------------------------------------------------------------------------------------------- |
| **401** | Missing, malformed, or unknown credential                                                                  |
| **403** | Authenticated, not allowed (including a key on a personal route, or ingest without the right Auth0 scopes) |
| **404** | Ingest when the org is not allowlisted — same as "this surface does not exist"                             |