---
title: "API keys"
subtitle: "Create, scope, limit, and revoke the keys your apps use to call Respan."
---

A Respan API key authenticates your calls to the gateway and the Respan API, and everything sent with it is logged in the key's project. Use one key per app and environment so you can limit or revoke each one on its own.

## Create a key

<Steps>
<Step title="Open API keys">

Go to **API keys** and click **New key**. The same page is at **Settings** › **API Keys**.

</Step>
<Step title="Choose the environment and permissions">

Name the key, pick an environment, and choose its permissions. Then click **Create**.

<img src={"/docs/images/gateway-quickstart/create-api-key-light.webp"} width="420" className="block dark:hidden" alt="The Create new key dialog with Name, Environment (Production or Test), and Permissions: Read, Write, Gateway, and Admin" />
<img src={"/docs/images/gateway-quickstart/create-api-key-dark.webp"} width="420" className="hidden dark:block" alt="The Create new key dialog with Name, Environment (Production or Test), and Permissions: Read, Write, Gateway, and Admin" />

</Step>
<Step title="Copy the key">

Click **Copy**, then **Done**. You won't see the key again, so save it now:

```bash
export RESPAN_API_KEY="your-respan-api-key"
```

</Step>
</Steps>

<Warning>
Treat a key like a password. Keep it out of source control and client-side code. If a key leaks, [revoke it](#revoke-a-key) and create a new one.
</Warning>

### Environment

**Production** and **Test** keep data apart. Logs, dashboards, and other data pages have an environment switch that shows **Production**, **Test**, or **All environments**. Spans and gateway requests sent with a test key, and Playground runs, show under **Test**. Your project's first key defaults to **Test**.

### Permissions

| Permission | Allows |
| --- | --- |
| **Read** | Viewing project data. |
| **Write** | Creating, editing, and deleting project data. Includes **Read**. |
| **Gateway** | Sending requests through the gateway. |
| **Admin** | Managing API keys and limits. |

New keys get **Read**, **Write**, and **Gateway**. Pick at least one permission.

## Find and tag keys

The list shows each key's prefix, tags, last use, expiry, spend, limits, status, and environment.

<img src={"/docs/images/admin/api-keys-list-light.png"} className="block dark:hidden" alt="The API keys list with columns for Key, Tags, Last used, Expires, Usage, Spend limit, Status (Active, Temporary, Revoked), and Env (Prod or Test)" />
<img src={"/docs/images/admin/api-keys-list-dark.png"} className="hidden dark:block" alt="The API keys list with columns for Key, Tags, Last used, Expires, Usage, Spend limit, Status (Active, Temporary, Revoked), and Env (Prod or Test)" />

- **Tag a key:** hover the row and click **Add tag**. Click **Tags** at the top to create or edit tags.
- **Find a key:** search by name, or filter and sort the list.
- **Copy a prefix:** click the prefix under the key's name.

Keys created with the [Temporary API keys](#create-keys-with-the-api) endpoint show a **Temporary** tag.

## Edit a key

Click a key in the list to open it. Change what you need, click **Save**, and confirm the changes. **Preview** shows or hides the key's prefix, creator, last use, and activity.

<img src={"/docs/images/admin/api-keys-detail-light.png"} className="block dark:hidden" alt="An API key's page with Preview, Revoke key, and Save at the top, the Permissions switches, and the Identity panel with prefix, creator, last used, and status" />
<img src={"/docs/images/admin/api-keys-detail-dark.png"} className="hidden dark:block" alt="An API key's page with Preview, Revoke key, and Save at the top, the Permissions switches, and the Identity panel with prefix, creator, last used, and status" />

Below **Permissions**, set the key's spend and usage caps, expiry, and alerts. See [Limits](/docs/ai-gateway/routing/limits).

## Revoke a key

Open the key and click **Revoke key**, or open the row's **⋯** menu in the list and click **Revoke key**. Click **Confirm**. Requests that use the key are rejected right away.

To replace a key without downtime, create the new key first, deploy it, and check that new requests show up in **Logs**. Then revoke the old key.

## Create keys with the API

Use the [Temporary API keys](/docs/apis/api-keys/create-temporary-api-key) endpoint to create short-lived keys, for example one per contractor or demo. The key you call it with needs the **Admin** permission. Each new key gets the calling key's permissions unless you set `permissions_override`, and it can't get more than the calling key has.

```bash
curl https://api.respan.ai/api/temporary-keys/ \
  -H "Authorization: Bearer $RESPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contractor demo",
    "is_test": true,
    "expiry_date": "2026-10-14T00:00:00Z",
    "spending_limit": 25,
    "limit_policies": [{"metric": "cost", "period": "day", "max_value": 5}]
  }'
```

The response's `api_key` is the only time you see the key. Manage its caps later with the [Limit policies API](/docs/apis/limit-policies/create-limit-policy).

Using your own OpenAI, Anthropic, or other provider keys? Click **BYOK** on the same page. See [Provider keys](/docs/documentation/admin/llm-provider-keys).