> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server.

# API keys

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

#### Open API keys

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

#### Choose the environment and permissions

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

![The Create new key dialog with Name, Environment (Production or Test), and Permissions: Read, Write, Gateway, and Admin](/docs/_fern-img/1780e946301a96a6ac3f872649a2639a6e460fd0d24a63156dac176abadb66d8.webp)![The Create new key dialog with Name, Environment (Production or Test), and Permissions: Read, Write, Gateway, and Admin](/docs/_fern-img/d667c8cacacbf220f2faa497ee1229ff4b8eb6f99bb04d90d8c407a8f66e01b8.webp)

#### 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"
```

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

### 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.

![The API keys list with columns for Key, Tags, Last used, Expires, Usage, Spend limit, Status (Active, Temporary, Revoked), and Env (Prod or Test)](/docs/_fern-img/bb12f98cbc35a2573db8ffa76b4a231498bcb35e8f449a31ab1321d3b6f31ec7.webp)![The API keys list with columns for Key, Tags, Last used, Expires, Usage, Spend limit, Status (Active, Temporary, Revoked), and Env (Prod or Test)](/docs/_fern-img/ed651648630c8b6348ff194fd54bffdb5b7728216bd867f6aa5a98b2a4fd50f0.webp)

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

![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](/docs/_fern-img/5f7d0ec04268a46aa796619a22dc454b26f227edeac047b5bf03ca12cf1c45fa.webp)![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](/docs/_fern-img/0f49eb3d85eafd872810bfdf0dfe7252cae912d689629e41f4e12f10750e7d67.webp)

Below **Permissions**, set the key's spend and usage caps, expiry, and alerts. See [Limits](/docs/documentation/features/gateway/limits#limit-an-api-key).

## 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 **Bring your own key** on the same page. See [Provider keys](/docs/documentation/admin/llm-provider-keys).