API Keys

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.

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

​

Scoping a key

A key carries a subset of the permission catalog. 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