# Authentication

URL: https://neattrim.com/docs/authentication

API keys, OAuth scopes and test mode for the Neattrim API.

Send every request with an `Authorization: Bearer <token>` header. The token is an API key or an OAuth access token.

## API keys

A key has one of two prefixes.

- `km_live_`: runs real jobs and draws from your allowance.
- `km_test_`: a key for building an integration, with lower rate limits. See [test mode](#test-mode) for what it does today.

Create, list and revoke keys on the [keys page](https://neattrim.com/account/keys). Key management needs a signed-in website session and cannot be done with a key. You can hold 10 live keys at once. Keep keys on a server. If a key leaks, revoke it and create a new one.

## OAuth for apps

An app that acts for a user uses OAuth 2.1 with PKCE. Assistants use the same authorisation server. Ask only for the scopes you need.

| Scope | What it allows |
| --- | --- |
| `media.process` | Run jobs |
| `files.read` | Read files |
| `files.write` | Upload and delete files |
| `library.read` | Read the library |
| `generate.voice` | Text to speech, dubbing, text to video, reels |
| `webhooks.write` | Manage webhooks |
| `account.read` | Read account and usage |

A request without the right scope gets `403 FORBIDDEN_SCOPE`.

## Test mode

Test keys allow 60 requests a minute and 5 jobs at once. Jobs that run only on sample files and draw nothing are not available yet: today a test key runs a job like a live key and draws from your allowance. To try the API without using much allowance, call `POST /v1/estimate` (it draws nothing) and run jobs on the short [sample files](https://neattrim.com/docs/quickstart#sample-files).

## Request ids

Every response carries an `X-Request-Id` header. Quote it when you contact support.
