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

# Authentication

> Use a Bearer token in the Authorization header. Keys are issued manually by The Data City.

The Data City v2 API uses Bearer-token authentication. Every request must send an `Authorization` header.

## Request format

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

Tokens are sent as plain HTTP Bearer credentials — no signing, no rotation header, no expiry parameter on the request itself.

<Note>
  Treat your API key like a password. Never check it into source control, ship it in a frontend bundle, or paste it into a shared chat. Store it as an environment variable or in a secrets manager.
</Note>

## Getting a key

API keys are issued manually by The Data City. To request one, email [support@thedatacity.com](mailto:support@thedatacity.com) with:

* The name of your organisation.
* The email address of the person who will hold the key.
* A short description of what you intend to use the API for.

A member of the team will provision the key and reply with the value.

## Replacing a key

If a key is leaked, lost, or you want to rotate it, email [support@thedatacity.com](mailto:support@thedatacity.com) and ask for a replacement. The old key will be disabled.

## Failure modes

| Status | Body                                      | Meaning                                                                     |
| ------ | ----------------------------------------- | --------------------------------------------------------------------------- |
| `401`  | `{"message":"Unauthenticated."}`          | Header missing or token wrong.                                              |
| `403`  | `{"message":"Invalid ability provided."}` | Token is valid but doesn't have the ability for that endpoint.              |
| `429`  | `{"message":"Too Many Attempts."}`        | Per-minute limit hit. See [Rate limits](/api-reference/guides/rate-limits). |

See [Errors](/api-reference/guides/errors) for the full envelope and other status codes.

## Abilities

Each token is scoped to one or more abilities (for example `companies:read`, `rtic:read`, `companies:companyDetails`). The endpoints you can call are the intersection of what your token allows and what the route requires. If a request returns `403` despite a valid token, the missing piece is an ability — contact support to widen the scope.

## Admin routes

A small number of `/admin/...` routes use a different `X-API-Key` header for internal use only. These are filtered out of the public reference and are not callable with a customer Bearer token.

<Snippet file="need-help.mdx" />