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

# Authentication

> API keys, permissions, expiry and revocation.

Every API call carries an API key in the `Authorization` header.

```bash curl theme={null}
curl https://myunite.ai/api/v1/quota \
  -H "Authorization: Bearer $UNITE_API_KEY"
```

```javascript JavaScript theme={null}
const res = await fetch("https://myunite.ai/api/v1/quota", {
  headers: { Authorization: `Bearer ${process.env.UNITE_API_KEY}` },
});
console.log(await res.json());
```

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

res = requests.get(
    "https://myunite.ai/api/v1/quota",
    headers={"Authorization": f"Bearer {os.environ['UNITE_API_KEY']}"},
)
print(res.json())
```

## Key format

The key starts with `unite_live_` followed by 40 letters and numbers. In the examples in this documentation we use the value `unite_live_YOUR_KEY_HERE`, which does not work.

Unite stores only an irreversible version of the key. That is why the full value is shown **only once**, when it is created. If you lose it, create another one and revoke the old one.

> [!WARNING]
>
> The key is a server secret. Do not use it in a browser, in a mobile app or in a repository. Whoever has the key can do everything its permissions allow.

## Who creates keys

Only workspace administrators create and revoke keys, under **API keys**, in the workspace dashboard. In the same dashboard, administrators also manage the [webhook](https://docs.myunite.ai/en/webhooks.md) endpoints. The API must be enabled for the workspace. If it is not, the screen says so and the API responds [`feature_not_enabled`](https://docs.myunite.ai/en/errors#feature_not_enabled).

## Permissions

Each key has one or more permissions (scopes).

| Scope | Allows |
| - | - |
| `pretests:read` | Read the catalog, the quota, the list and the detail of pre-tests, and download the PDF. |
| `pretests:write` | Request the file upload address and create pre-tests. |
| `webhooks:manage` | Create, list and delete [webhook](https://docs.myunite.ai/en/webhooks.md) endpoints, send a test and view deliveries. |

For the complete [first pre-test](https://docs.myunite.ai/en/quickstart.md) flow, the key needs both scopes. Without the required scope, the response is [`insufficient_scope`](https://docs.myunite.ai/en/errors#insufficient_scope). Give each integration only what it uses.

Receiving notifications through [webhooks](https://docs.myunite.ai/en/webhooks.md) requires the `webhooks:manage` scope only to register and manage the endpoints. The events themselves reach your server without using the key.

## Expiry

When creating, choose 30, 90 or 365 days, or no expiry. Once expired, the key responds [`api_key_expired`](https://docs.myunite.ai/en/errors#api_key_expired). Prefer keys with an expiry and replace them before they expire.

## Revocation

Any administrator revokes a key on the same screen. Revocation takes effect immediately and cannot be undone: the key starts responding [`api_key_revoked`](https://docs.myunite.ai/en/errors#api_key_revoked). Revoke whenever you suspect a leak.

## The key acts on behalf of its creator

The key represents the member who created it. Pre-tests created by it are recorded under that person's name. If that person leaves the workspace or loses access to it, the key stops working. The [webhook](https://docs.myunite.ai/en/webhooks.md) endpoints created by that person are also disabled (`disabledReason: "creator_removed"`); revoking a key, by contrast, does not affect endpoints.

On every call, Unite checks again that this person is still an active member of the workspace. If they leave the workspace or lose access, the key **stops working** and responds [`key_owner_not_member`](https://docs.myunite.ai/en/errors#key_owner_not_member), even if it was not revoked. For a long-lived integration, create the key with an account that should stay in the workspace.

## Isolation

The key only sees the workspace where it was created. Ids from another workspace respond as if they did not exist (`404`).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.