Keys
Make a key, choose what it may do, and keep it safe.
Every call carries a key in the Authorization header:
GET /v1/me HTTP/1.1
Host: api.taad.app
Authorization: Bearer taad_eyJhbGciOiJFZERTQSIsImtpZCI6ImsxIiwidHlwIjoiSldUIn0.eyJpc3Mi…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. 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
| 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
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
Keys starting taadtest_ work in your 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
A key is a JSON Web Token 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
- Only in the
Authorizationheader, 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.