Skip to content
AvraAvra
Esc
↑↓navigate↵open⌘Jpreview
On this page

API keys

Create, rotate, rename, and delete the API keys your systems use, and check which workspace a key belongs to.

An API key is the credential your systems send to the Avra API. Each key belongs to one workspace and authenticates calls to that workspace only. Creators and Developers, the roles that can manage API keys, manage them under Settings → Workspace → API keys.

A key’s life is short to describe. You create it in the workspace it’s for, copy it once into your secret manager, and send it as a bearer token. You rotate it on a schedule, when someone who knew it leaves, or at once if it may have leaked. You delete it when nothing uses it anymore.

Create a key

Open the workspace's keys

Switch to the workspace the key is for, and open Settings → Workspace → API keys.

Start a new key

Select Create Key.

Name it

Optionally, enter a Name of up to 50 characters that says where the key is used, such as credit-engine-prod.

Create it

Select Create Key.

Copy it now

Copy the key from the API Key Created dialog, store it in your secret manager, and select Done.

Without permission to manage API keys, Create Key is turned off, with a tooltip saying why, and so are the actions on each key.

Use a key

Send the key as a bearer token in the Authorization header of every request. This call checks a key before you wire it in: it returns the key’s ID and name, and the workspace and organization it belongs to.

curl https://api.avra.ai/v1/api/workspace/keys/introspect \
  -H "Authorization: Bearer $AVRA_API_KEY"
{
  "key": { "id": "…", "name": "credit-engine-prod" },
  "workspace": { "id": "…", "name": "production", "env": "production" },
  "organization": { "id": "…", "name": "Acme" }
}

A request with a missing or invalid key gets 401 Unauthorized. Limits apply per key: live predictions allow about 100 requests per 10 seconds for each one. See Live predictions.

Find a key

The key list shows each key’s Name, Key ID, Created by, and Created date. Search it by name with the search box at the top of the list.

By default, the list shows only the keys you created. Turn off Created by me to see every key in the workspace.

A key whose creator has left the organization shows Removed user under Created by. The key keeps working until someone rotates or deletes it.

Rotate a key

Rotating generates a new key and retires the previous one. You choose when the previous key stops working: at once, or 30 minutes later.

Open the key's menu

In Settings → Workspace → API keys, open the menu at the end of the key’s row and select Rotate Key.

Choose when the previous key stops

Turn on Keep the previous key working for 30 minutes for a planned rollout, so running integrations survive the swap. Leave it off when you believe the key is compromised.

Rotate

Select Rotate Key.

Copy the new key

Copy the new key from the dialog, store it in your secret manager, and select Done. Then update your systems with it, within 30 minutes if you kept the previous key working.

With the option off, the previous key is revoked as soon as you rotate, and anything still using it starts receiving 401 responses.

Rename a key

Open the menu at the end of the key’s row, select Rename, enter the new Name, and select Save Changes. Renaming changes only the label: the key itself keeps working.

Delete a key

Open the menu at the end of the key’s row, select Delete, and confirm with Delete Key. Deleting a key can’t be undone, and systems still using it lose access. Create a new key if you need one again.

Good practices

Create one key for each system and environment, named for where it’s used. You can then rotate one key without touching the others, and tell them apart in the usage log, which names the key behind each prediction. Rotate keys regularly. When someone leaves your organization, rotate or delete the keys they created: removing a member doesn’t revoke them. See Team management.

Keys in the logs

Creating, rotating, renaming, and deleting keys is recorded in the audit log, under Observability → Audit. A rotation appears there as api-key-recycling. The same changes are sent as the api-key-creation, api-key-recycling, api-key-renaming, and api-key-deletion webhook events. See Audit and usage logs and Webhooks.

Where to go next

Was this page helpful?