Authentication and API keys
How to send your API key, how many keys you can hold, what a key can and cannot do, what to do when one leaks, and how to disconnect an AI assistant.
Send the key in the Authorization header
Authorization: Bearer YOUR_API_KEYThat header is the only place the API reads a key.
- Never put a key in a URL (
?api_key=…). URLs end up in logs, in browser history and in shared links. The API refuses such a request with400 api_key_in_query. Treat that key as exposed: revoke it and create a new one. - Call
https://author.trueroyalties.com/api/v1. The same path ontrueroyalties.comanswers404 wrong_host. We never redirect it: a client following a redirect to another address drops your key on the way. - Call the API from a spreadsheet, a script or a server, not from the code of a web page: anyone visiting the page could read the key.
What a key can do
- Read every figure of your account, on every endpoint.
- Change nothing. The API is read-only.
- Share the limits of your account: all your keys and connected AI assistants count together, so a second key does not give you more requests. See Limits and errors.
Create a key
Settings → API → Create a key.
- The name can be up to 40 characters. Use the tool's name, so you know which key to revoke later.
- The key is shown once. We keep only a fingerprint of it, so nobody can show it again — not even us. Store it in a password manager or in your tool's secret settings.
- You can hold 10 keys at a time.
- The public demo account cannot create keys.
The key list
Each key shows its name, its first characters (tr_live_ab12…), when it was
created and when it was last used.
"Last used" is updated at most once an hour, so a key used a few minutes ago can still show an earlier time.
Revoke a key
Open the ⋯ menu of the key, then Revoke.
It takes effect immediately: the next request with that key gets
401 unauthorized, the same answer as a key that never existed. A revoked key
cannot be restored — create a new one.
AI assistants connected without a key
claude.ai and ChatGPT use no key: you sign in to TrueRoyalties from the assistant and click Allow. The assistant then gets its own access, which can only read. How to connect one: Connect an AI assistant.
- Settings → API → Connected apps lists each assistant, the address that asked for access, when you connected it and when it last read your figures (updated at most once an hour).
- Unverified next to a name means the app registered itself without proving its address. Keep it only if you connected it yourself.
- To stop one, open its ⋯ menu, then Disconnect. It takes effect immediately. To use it again, connect it again from the assistant.
When a request is refused
| Answer | Why | What to do |
|---|---|---|
401 unauthorized | No Authorization header, or a key that is wrong or revoked | Check the header and the key |
403 subscription_inactive | Your subscription has ended | Subscribe in Settings → Billing |
400 api_key_in_query | The key was in the URL | Move it to the header, then revoke it |
404 wrong_host | The request went to trueroyalties.com | Use author.trueroyalties.com |
Every other code is described in Limits and errors.
The public demo key
The API reference pre-fills its Try it button with a public key. It reads only the demo account, whose figures are synthetic, and it is limited to 10 requests per minute, shared by every visitor. It cannot read your account: use your own key for that.