> ## Documentation Index
> Fetch the complete documentation index at: https://to11.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API Keys

> Create scoped API keys for programmatic access, and rotate or revoke them.

API keys give applications programmatic access to to11 — both the gateway and the management API. Each key is scoped to a set of permissions, so a key can be granted only what it needs. Keys are managed under **Settings → API keys**.

## Creating a key

Choose **Create key** to open a short wizard. A key belongs to an **environment** — `live` or `test` — so you can keep production and testing credentials separate, and the wizard then walks through:

1. **Scope** — the level the key acts at: organization, workspace, or project. You can only create a key at a level you have access to.
2. **Permissions** — start from a preset and refine:

   * **Write** — read and change configuration (prompts, routing, providers, ingestion).
   * **Read** — read-only access.
   * **Ingest** — send telemetry and read routing, for collectors and SDKs.
   * **Custom** — pick exactly the permissions you want from the catalog.

   You also set an **expiry** here — a preset (30, 90, or 365 days), a custom number of days, or never.
3. **Review** — name the key and confirm its scope, permissions, and expiry.
4. **Reveal** — the secret is shown once.

<Warning>
  The key secret is shown only once, at creation. Copy it and store it securely — it can't be retrieved again. If you lose it, rotate the key.
</Warning>

Creating a key requires the `keys:create` permission at the chosen scope.

## Scoping a key

A key carries a subset of the [permission catalog](/docs/platform/roles-and-permissions). Grant only what the application needs: a telemetry collector needs ingestion, not the ability to change routing. A key can never be created with permissions beyond what its creator holds.

## Rotating a key

Rotation issues a replacement key with the same scope, permissions, and expiry, so you can roll the secret without re-granting access. You choose a **grace period** — immediately, or 1 hour, 24 hours, or 7 days — during which the old secret keeps working, giving you time to deploy the new one before the old one stops. Rotation requires `keys:rotate`.

## Revoking a key

Revoking a key disables it immediately and permanently — there's no grace period. Requests presenting a revoked key are rejected. Use rotation, not revocation, when you only need to replace a leaked secret without an outage. Revoking requires `keys:revoke`.

## Usage and audit

Each key has two views from its row:

* **Usage** — recent call volume over the last 7 days, with a per-key trend.
* **Audit** — a security log of the key's lifecycle: created, used, rotated, revoked, and any scope-denied attempts. The log is **retained for 13 months** and can be **exported as CSV**.

## Next steps

<CardGroup cols={2}>
  <Card title="Roles & permissions" icon="shield-check" href="/docs/platform/roles-and-permissions">
    The scopes a key can carry.
  </Card>

  <Card title="Audit logs" icon="scroll-text" href="/docs/platform/audit-logs">
    Track configuration changes across the project.
  </Card>
</CardGroup>