API Keys
Create API keys that act as you, or as a standalone service account with its own roles.
An API key authenticates calls to Airia's APIs — running an agent from your application, driving the platform from a script, or connecting a third-party tool. Keys live under Settings → Developer → API Keys, and every request presents one in the X-API-Key header.
Every key is one of two kinds, and the difference is whose permissions it carries:
- a personal access token acts as you, and
- a service account acts as an identity of its own, with roles you choose.
You pick between them with a single field when you create the key.
Choose a key type
| Personal access token | Service account | |
|---|---|---|
| How you create it | Leave Roles (optional) empty | Select one or more roles |
| Whose permissions it uses | Yours | Only the roles you selected |
| If your own roles change | The key changes with you | Unaffected — it keeps the roles you gave it |
| If your user is removed or you lose access | The key stops working | Keeps working |
| Best for | Personal scripts, experiments, getting started | Production integrations, automation, anything that must outlive one person |
A personal access token is the default and the simplest thing to reason about: the key can do exactly what you can do, no more. Because that link is live, it also means the key quietly gains any access you gain later — which is why it is the wrong choice for a long-lived integration.
A service account is the better choice for anything real. Give it only the roles the integration actually needs and it stays at that level of access no matter what happens to your own account.
One nuance worth being precise about: a service account is insulated from changes to your access, not from changes to the roles themselves. If someone edits a role the key is bound to, the key's access changes with it — and that includes a role you happen to hold too. See Permissions stay live.
Think of it as the difference between lending someone your own badge and issuing the robot its own. Prefer issuing the robot its own.
Create an API key
Open API Keys
Go to Settings → Developer → API Keys and select Generate Key.
Name the key
Enter a Name (required). Use something that identifies the integration, not the person — the name is how you will recognise the key months later.
Set the scope
Choose a Scope (required). Select All projects to let the key reach everything in the account, or pick a single project to confine it there. A project-scoped key can only see that project's data.
Decide on conversations
Turn on Include Conversations if the integration needs to read or write chat conversations. Leave it off otherwise — conversation endpoints reject keys without it.
Choose roles, or don't
Leave Roles (optional) empty to create a personal access token bound to your own permissions.
Select one or more roles to create a service account instead. Both default and custom roles are available, and you can combine several — the key gets the union of everything they grant. See Choosing roles for a service account below.
If you pick a role that is itself scoped to specific projects — Project Admin, or a custom role copied from it — the key needs a project scope too, so go back and choose a project rather than All projects. Airia rejects the combination instead of creating a key that could never act anywhere.
Copy the key, then create it
The Key field already shows the generated value. Copy it now and store it somewhere safe.
Click Create to save the key.
The full key is shown once. After you close the dialog, the list only ever displays the first and last four characters, and there is no way to reveal or recover the rest. If you lose a key, delete it and create a new one.
Choosing roles for a service account
Grant the least access that does the job. A service account exists precisely so you don't have to hand a production integration your own administrator permissions.
You can only assign roles whose permissions you already hold. Airia compares the permissions of the roles you selected against your own; if a role includes something you don't have, the key is not created and the error names the permission it objected to. A Platform Admin bypasses this comparison, holding everything already.
That check runs when the key is created, so it stops you issuing a key more powerful than yourself. It is not a standing ceiling on the key: because permissions are resolved live, anyone who can edit a role the key is bound to can widen what the key can do later. See Permissions stay live.
Platform Admin cannot be assigned to a key, by anyone. It is not offered in the picker, and the API rejects a request that names it — on its own or alongside other roles. Choose Admin when an integration needs access across the whole account.
See Custom Roles for how roles are built and Permissions Reference for what each permission controls.
A key's type and its roles are fixed when you create it. To change either, create a replacement key, point the integration at it, and delete the old one.
Permissions stay live
A key never carries a frozen copy of its permissions. They are resolved fresh on every request, from the roles the key is bound to.
That has a practical consequence worth planning around: editing a role changes every key bound to it. Add a permission to a role and its service-account keys can immediately use it; remove one and they immediately cannot. The same is true of a personal access token and its owner's roles.
Changes are not always instant — allow up to 5 minutes to reach keys already in use, the same delay as any role change.
When the creating user is deleted
This is the clearest practical difference between the two types, and the main reason to prefer a service account for anything in production.
| Personal access token | Service account | |
|---|---|---|
| What happens to the key | Deleted with the user | Kept |
| Do integrations using it keep working? | No | Yes, unchanged |
A personal access token is an extension of one person's access, so it goes when they do. That is deliberate: leaving it alive would leave a departed employee's permissions in use, which is exactly what offboarding is supposed to end. Legacy keys follow the same rule — they are also bound to whoever created them, so they are deleted with that user too.
A service account belongs to the account rather than to whoever happened to create it. Removing that person — whether an administrator deletes them or your identity provider deprovisions them — does not touch the key, and anything built on it keeps running.
If a production integration is running on a personal access token or a legacy key, it will break the day that person is offboarded. Replace it with a service account before that happens.
Because a service account outlives its creator, give it a name that explains what it is for. "Billing sync" tells the next administrator what breaks if they delete it; "Dave's key" does not.
Reading the key list
The list shows one row per key, with Scope, whether conversations are included, and when it was created. Three further columns help you audit:
- Type — Personal access token or Service account. A key with no recorded creator shows Unknown instead, because the type is worked out from what the key is bound to; these are old automation keys that predate Airia capturing a creator. Any key you create now is one of the first two.
- Creator — who created the key. A service-account key whose creator has since been removed shows Deleted user; that is expected, since a service account is designed to outlive the person who set it up. Unknown here means no creator was ever recorded — the same keys that show Unknown under Type, for the same reason.
- Last used — the date the key last made a request, or Never if it never has. This is tracked to the day, not the minute, so treat it as a signal of whether a key is still in use rather than a precise timestamp.
Together these answer the question that matters during a review: is anything still using this key, and what happens to it if its creator leaves? A key that has never been used, or that hasn't been used in months, is a good candidate for deletion.
Deleting a key takes effect immediately and cannot be undone — any application still presenting it will start failing.
Checking what a key can do
Click any key in the list to open it. The name and the key value are read-only; depending on your permissions you may be able to change Include Conversations, and nothing else.
What the dialog tells you depends on the key's type:
- A service account lists the Roles it carries. If every role it was given has since been deleted it reads No active roles — the key still authenticates but can do nothing, so it needs replacing.
- A personal access token shows whose permissions it runs on instead — "Uses Dana's permissions", or a note that the creator has been deleted or was never recorded.
Roles are fixed when the key is created and cannot be edited here. To change them, create a replacement key and delete this one.
Legacy keys
Keys created before roles existed are marked with a Legacy badge, and a banner shows the date they stop working.
Legacy keys behave like personal access tokens: they are tied to whoever created them, and they are deleted along with that user. So a legacy key can disappear two ways — when its creator is removed, or when you replace it ahead of the sunset date.
The Legacy badge is independent of the Type column: it marks the sunset, not the kind of key. Most legacy keys read Personal access token, or Unknown where no creator was recorded.
Nothing deletes legacy keys automatically at the sunset date, so you can migrate on your own schedule — but they will need replacing before it. Recreate each one as the type it should have been, ideally a service account with just the roles it needs, then update the application and delete the old key.
Migrating a legacy key to a service account fixes both problems at once: it survives the sunset date, and it stops depending on whoever originally created it.
Use the filter above the list to show only legacy keys and see what is left to migrate.
Using a key
Send the key in the X-API-Key header on every request.
If a call returns 403 Forbidden, the key authenticated but does not hold the permissions that endpoint requires — check the roles it was given. A 401 means the key itself was not accepted.
To find the endpoint for a particular agent and the code examples for calling it, see API Interface Configuration.
API keys are not the same thing as AI Gateway keys, which start with agk-, are sent a different way, and are managed per gateway configuration — see AI Gateway. They are also distinct from credentials, which are keys you bring to Airia so agents can reach external services — see Credential Management.