> ## 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 applications, CI, and scripts, and rotate or revoke them.

API keys give machines programmatic access to to11: an application that renders prompts with the [SDK](https://to11.ai/docs/reference/typescript-sdk.md), a CI job that runs the [CLI](https://to11.ai/docs/reference/cli.md), or your own scripts against the API. Each key carries a set of permissions, so a key can be granted only what it needs. People use their own sign-in instead. Keys are managed under **Settings → API keys**, in the **Organization** section.

## Creating a key

Choose **Create API key** to open a short wizard:

1. **Scope** — the key's name, and the level it acts at: **Organization** (every workspace and project), **Workspace** (every project in one workspace), or **Project** (one project). You can only create a key at a level you have access to.
2. **Permissions** — start from a preset and refine:

   * **Write** — read prompts and skills, create, edit, archive, and publish them, and upload session transcripts.
   * **Read** — read prompts and skills only. This is the default.
   * **Ingest** — upload session transcripts only.
   * **Custom** — pick exactly the permissions you want.

   You also set an **expiry** here: 30 days, 90 days (the default), 1 year, a custom number of days, or never.
3. **Review** — confirm the key's 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.

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

## Scoping a key

A key carries a subset of the [permission catalog](https://to11.ai/docs/platform/roles-and-permissions.md). These are the permissions a key can hold:

| Permission | Lets the key |
| - | - |
| `prompt:read` | Read prompts and skills, and render them |
| `prompt:create` | Create prompts and skills, and store new versions |
| `prompt:update` | Change a prompt's name, description, and tags |
| `prompt:archive` | Archive and restore prompts |
| `project:read` | Read the project, and resolve `workspace/project` names to it |
| `ingest:write` | Upload [session](https://to11.ai/docs/sessions/overview.md) transcripts |
| `sessions:read` | Read the project's sessions |
| `org_audit:read`, `org_audit:export` | Read and export the organization's [admin audit log](https://to11.ai/docs/platform/audit-logs.md#the-admin-audit-log). Marked **Sensitive** in the wizard |

Grant only what the machine needs: a CI job that uploads sessions needs `ingest:write`, not the ability to publish prompts. A key can never be created with permissions beyond what its creator holds, and no key can be given `keys:create`, so the keys you create can't create other keys.

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

## Next steps

> [card] [Roles & permissions](https://to11.ai/docs/platform/roles-and-permissions.md)
>
> The scopes a key can carry.

> [card] [Audit logs](https://to11.ai/docs/platform/audit-logs.md)
>
> Key creation, rotation, and revocation are recorded in the admin audit log.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.