---
title: API keys
description: 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

1. **Open the workspace's keys**

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

2. **Start a new key**

    Select **Create Key**.

3. **Name it**

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

4. **Create it**

    Select **Create Key**.

5. **Copy it now**

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

:::warning[You see the key only once]
The dashboard never shows a key again after you close the **API Key Created** dialog. Keep keys in a secret manager, never in source control. If you lose one, rotate it to get a new one.
:::

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.

```bash
curl https://api.avra.ai/v1/api/workspace/keys/introspect \
  -H "Authorization: Bearer $AVRA_API_KEY"
```

```json
{
  "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](/core/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.

```mermaid
flowchart LR
  R["Rotate Key"] --> Q{"Keep the<br/>previous key<br/>working?"}
  Q -->|"off: compromised key"| N["Previous key<br/>revoked at once"]
  Q -->|"on: planned rollout"| G["Previous key works<br/>30 more minutes"]
  N --> U["Update your systems<br/>with the new key"]
  G --> U
```

1. **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**.

2. **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.

3. **Rotate**

    Select **Rotate Key**.

4. **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](/dashboard/team-management#remove-a-member).

## 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](/dashboard/audit-logs) and [Webhooks](/core/webhooks).

## Where to go next

**[Live predictions](/core/predictions)**

Call a model with your new key

**[Audit and usage logs](/dashboard/audit-logs)**

See what each key did

**[Authentication & sessions](/dashboard/authentication)**

How people sign in to the dashboard
