# Keys (/api/authentication)

Every call carries a key in the `Authorization` header:

```http
GET /v1/me HTTP/1.1
Host: api.taad.app
Authorization: Bearer taad_eyJhbGciOiJFZERTQSIsImtpZCI6ImsxIiwidHlwIjoiSldUIn0.eyJpc3Mi…
```

## Making a key [#making-a-key]

Keys are made in Taad, in **Settings › Developers › Keys**, never by the API itself. You'll be asked to sign in again if you last signed in more than a few minutes ago.

The API is for those who pay for Taad: you need a paid plan or money in your [API wallet](/api/pricing). If neither is true any more, calls answer `402 payment_required` until it is; your keys are kept and work again once you pay.

## Personal and organization keys [#personal-and-organization-keys]

| | Made by | Reaches | Paid from |
| --- | --- | --- | --- |
| **Personal key** | you | your **Personal** workspace only | your plan's minutes (for audio, if you allow it), then your API wallet |
| **Organization key** | the organization's **owner** | **everything filed in that organization**, whoever recorded it | the organization's API wallet |

If you're in an organization and want API access of your own, make a personal key: it reaches what you file in your Personal workspace, never the organization's.

## What a key may do [#what-a-key-may-do]

When you make a key, Taad asks what it's for and picks its **scopes**:

| Scope | Lets the key |
| --- | --- |
| `recordings:read` | read recordings, transcripts, notes and speakers; search; export |
| `recordings:write` | rename recordings and speakers, set your own ids and labels, send audio, rewrite notes |
| `audio:read` | download the audio itself |
| `todos:read`, `todos:write` | read, or also add and change, to-dos |
| `calendar:read`, `calendar:write` | read, or also add and change, calendar events |
| `ask` | ask questions across your recordings |
| `webhooks` | add and manage webhook endpoints |

A key can also be **read-only** (fixed for its life), have an **expiry date**, and carry a **weekly spending cap** that you set. `GET /v1/me` tells you all of it.

## Test keys [#test-keys]

Keys starting `taadtest_` work in your [sandbox](/api/sandbox): sample recordings, instant fixed results, never charged. Use them while you build; switch to a live key (`taad_…`) when you're ready.

## What's inside a key [#whats-inside-a-key]

A key is a [JSON Web Token](https://jwt.io) behind the `taad_` prefix, signed by us. Anyone can read what's inside, so it holds nothing private: only the key's own id, whether it's live or test, and a random secret. What the key may do is kept on our side, so it can change without a new key.

We check every key twice: its signature, then the key itself, on every call. So a revoked key stops at its very next request. Our public signing keys are at `https://api.taad.app/v1/.well-known/jwks.json`.

## Keeping it safe [#keeping-it-safe]

- **Only in the `Authorization` header**, from your server. A key in a URL ends up in logs: those calls are refused (`key_in_url`). Calls from a web page are refused too (`browser_not_allowed`).
- **Roll** a key in Settings to get a new secret. The old one keeps working for the time you choose (now, an hour, a day or a week), so you can deploy the new one first.
- **Revoke** a key and it stops at once.
- **Lost it?** It's shown once, and we don't keep it: roll it for a new one.