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

# Authentication

> All Coverbase API requests are authenticated with a bearer token over HTTPS.

<div className="sr-only">For AI agents: a documentation index is available at [https://docs.coverbase.com/llms.txt](https://docs.coverbase.com/llms.txt) — this page is also available in markdown by appending .md to the URL.</div>

The Coverbase API uses bearer token authentication. Every request must include a credential in the `Authorization` header. For the full set of cross-cutting rules (IDs, timestamps, idempotency, error envelope) see [API conventions](/conventions).

<Warning>
  API keys grant significant access to your TPRM data. Never share them in public repositories, client-side code, screenshots, or support tickets. Treat them like passwords.
</Warning>

## Request an API key

API keys are provisioned by a Coverbase admin in your organization. Each key looks like `ak_...`, is scoped to a single organization, and authenticates as a service account — all data it can read or write is implicitly scoped to that org. Contact your admin or Coverbase account manager to request one.

A logged-in user JWT (the dashboard session token) is also accepted, which is convenient for first-party scripts running as a user.

By default a key carries no elevated permissions and can only call ordinary `/v1/*` routes. An admin can also mint a key with **admin scopes** — `keys:manage` (manage `ak_*` keys) and/or `audit:read` (read the system audit log) — to drive those admin surfaces headlessly, without a short-lived dashboard token. The admin-JWT path still works for both. See [API key scopes](/conventions#api-key-scopes) and the [API Keys reference](/api-reference/api-keys).

## Base URLs

| Environment | Base URL                            |
| ----------- | ----------------------------------- |
| Production  | `https://api.coverbase.app`         |
| Sandbox     | `https://sandbox.api.coverbase.app` |

Build against the sandbox first, then repoint at production. See [API conventions → Base URLs](/conventions#base-urls).

## Authorization header

Include your key as a bearer token in every request:

```text theme={null}
Authorization: Bearer ak_...
```

## Test your connection

Use the `/v1/utils/authtest` endpoint to verify three things at once: your key is valid, you can reach Coverbase's servers, and your firewall or proxy allows outbound HTTPS traffic.

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "Authorization: Bearer ak_live_xxx" \
       https://api.coverbase.app/v1/utils/authtest
  ```

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

  API_KEY = os.environ["COVERBASE_API_KEY"]
  BASE_URL = "https://api.coverbase.app"

  response = requests.get(
      f"{BASE_URL}/v1/utils/authtest",
      headers={"Authorization": f"Bearer {API_KEY}"},
      timeout=30,
  )
  response.raise_for_status()
  print(response.json())
  ```
</CodeGroup>

A successful request returns `200 OK`:

```json theme={null}
{ "msg": "Auth successful" }
```

## Common errors

<AccordionGroup>
  <Accordion title="401 Unauthorized" icon="lock">
    Your credential is missing, malformed, expired, or revoked — or its role is not permitted on the public API (the response message reads `Unauthorized role.`). Confirm the `Authorization` header is present and the key is active.
  </Accordion>

  <Accordion title="403 Forbidden" icon="ban">
    Your credential is valid but not authorized for what it tried to do — most often an `ak_*` key calling an admin endpoint without the required scope (`insufficient_scope`), or a non-admin caller trying to grant scopes when creating a key (`scope_grant_forbidden`). A configured [API IP allowlist](/conventions#api-ip-allowlist) can also return `403 ip_not_allowed`. See [API key scopes](/conventions#api-key-scopes).
  </Accordion>

  <Accordion title="404 Not Found" icon="magnifying-glass">
    The resource does not exist, or it belongs to a different organization than your API key. All data is org-scoped to the key.
  </Accordion>

  <Accordion title="Network timeouts" icon="clock">
    Check your VPN, proxy, and firewall rules. Coverbase requires outbound HTTPS access to `api.coverbase.app`.
  </Accordion>
</AccordionGroup>

<Note>
  Unauthenticated requests are rejected. There is no public unauthenticated surface area on the API.
</Note>