Keys and security
Keys and rotation
How a key acts as its maker, how long it lives, what ends it early, and how to rotate keys without stopping your work.
What a key is
A key is a long secret that starts with pan_. A program sends it in the Authorization header of every call:
GET /api/v1/me HTTP/1.1
Host: panlytics.net
Authorization: Bearer pan_...The key acts as the person who made it, in the company it was made in. Every call runs through the same checks the person's own pages use, with the person's role read fresh on each call, and then the fence on top. Whatever the key does is recorded under the person's name and marked as done with a key. In the audit log it reads "name (AI key)".
Panlytics never stores the key itself. It keeps a keyed fingerprint (an HMAC: a hash that also needs a secret only the server holds), so a copy of the database is not a copy of anybody's keys. That is also why the key is shown only once.
Who may make one
Two things must be true:
- Developer mode is on for the company. The CEO switches it on, on the organisation's Developer page.
- The person's role holds "Make keys for programs and AI agents". The CEO holds it. Only the CEO can put it on another role.
Making a key also needs a recent sign-in: if you signed in a while ago, Panlytics asks you to confirm your password or passkey first. A key can never make another key, so a program can never renew its own access.
Each person may hold five live keys at once. Revoke one you no longer use to make room for a new one.
How long a key lives
A key ends 1 to 5 hours after it is made. The CEO chooses the period for the whole company, and one hour is the default. Shortening the period shortens every live key at once; lengthening it only affects keys made afterwards. No key ever works longer than five hours, whatever the setting says.
The end is a fixed moment, in key.endsAt from GET /v1/me. Using a key does not extend it.
When a key reaches its end, its maker is told once, in the bell.
What ends a key early
| What happens | Which keys end |
|---|---|
| The maker revokes the key on their Developer page | That key |
| The CEO revokes it from Every key in the company | That key |
| The CEO switches developer mode off | Every key in the company |
| The CEO shortens the period | Every key older than the new period |
| The maker is removed from the company | The maker's keys in that company |
| The maker is switched off or banned | Every key the maker holds |
| The maker changes their password and signs out other devices, or signs out everywhere | Every key the maker holds |
| The maker's role loses "Make keys for programs and AI agents", or the maker moves to a role without it | Every key the maker holds in that company, revoked at once |
An ended or revoked key answers 401 with the code api.key_refused on every call. It stays on the Developer pages for a week, marked as ended, so you can see when it stopped.
Rotating keys
Because a key ends within hours, rotation is part of normal work rather than an emergency.
- Make the new key before you need it. You can hold up to five, so the old and the new can overlap.
- Switch your program or agent to the new key.
- Revoke the old key, or let it end on its own.
For a program that runs on a schedule, make the key at the start of each run and let it end afterwards. For an agent, see When the key ends.
Keeping a key safe
- Put the key in an environment variable or your platform's secret store, never in a file that is committed.
- Never log it, print it or send it in a URL. Panlytics reads it only from the
Authorizationheader. - Give each program and each agent its own key, with a label that says which, so you can revoke one without stopping the others.
- A key starts with
pan_, which secret scanners look for. If one is found in a repository, revoke it.