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 choose the type first, before anything else, when you create the key.
Never share a personal access token. It is your identity in key form. Anyone holding it can do everything you can do in Airia, including using any credentials tied to your user. If another person or system needs a key, create a service account for it instead.
Choose a key type
| Personal access token | Service account | |
|---|---|---|
| How you create it | Choose Personal access token | Choose Service account (the default) and select at least one role |
| 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 |
| Credentials tied to your user | Can use them, as you | Cannot. It is not you. |
| Safe to share with another person or system | No, never | Yes. That is what it is for. |
| Include Conversations | Not available | Available |
| Best for | Your own scripts and experiments | Production integrations, automation, shared keys, anything that must outlive one person |
A personal access token is the simplest thing to reason about: the key can do exactly what you can do, no more. That includes acting on your behalf with any credentials tied to your user, which is why it must stay with you. Because that link is live, it also means the key quietly gains any access you gain later. That's why it's the wrong choice for a long-lived integration, and for anything you would hand to someone else.
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.
Choose the type
The Create New Airia Key dialog opens with a Type choice at the top:
- Service account (selected by default) — its own identity, limited to the roles you pick. Use it when the key is shared or used by an integration.
- Personal access token — acts as you, with your permissions and access to your personal credentials. Choosing it shows a Never share a personal access token warning. Choose it only for a key that will stay with you.
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.
Choose roles (service account only)
A service account needs at least one role, and Create stays disabled until you select one. Both default and custom roles are available, except Platform Admin, which can't be assigned. 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.
A personal access token has no Roles field: it always uses your own permissions.
Decide on conversations (service account only)
Include Conversations appears only for a service account. Turning it on lets the key read, create, edit and delete conversations and messages for every user in the account, not just its own. Turn it on only if the integration needs that; leave it off otherwise — conversation endpoints reject keys without it.
A personal access token can't include conversations, so the option isn't shown when you choose that type.
Create the key, then copy it
Click Create. The dialog then shows the new key with a copy button and a warning to copy it now; for a personal access token the warning is titled Never share a personal access token. Copy the key and store it somewhere safe.
Click Done to close the dialog.
The full key is shown once, right after you click Create. 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 its Scope, when it was created, and whether conversations are included. 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. Everything in the dialog is read-only: a key's type, scope, roles and Include Conversations are all set when it is created and can't be changed. The key itself is masked, showing only its first and last four characters.
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.
To change anything about a key, create a replacement key with the settings you need, move your application over to it, and delete the old 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.
Creating keys with the API
The same rules apply when you create keys through the API rather than the dialog. A key is a service account when the create request includes roleIds, and a personal access token when it doesn't.
Asking for the Conversations scope on a personal access token is refused when the key is created (POST /v1/ApiKeys). The response is:
{
"code": "CONVERSATIONS_REQUIRES_SERVICE_ACCOUNT",
"message": "The Conversations scope is only available for service account keys. Select one or more roles to create a service account key."
}with status 400 Bad Request. To fix it, include roleIds in the create request so the key becomes a service account.
The Conversations scope can't be added to or removed from an existing key. A PATCH /v1/ApiKeys/{id} request that would change it, on any type of key, is refused with status 400 Bad Request:
{
"code": "CONVERSATIONS_SCOPE_IMMUTABLE",
"message": "The Conversations scope is set when an API key is created and can't be changed. Create a new key to change it."
}Create a replacement key with the scope you need instead.
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.