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

# API keys

An API key lets your scripts, such as a CI pipeline, start and follow sessions without signing in. Each key works in **one project and one environment**, and only does what its scopes allow.

> **Note**
>
> Everyone can see a project's keys. Only Admins and the Owner can create and revoke them.

## Create a key

#### Open API keys

Open the project, choose the **Settings** tab, then **API keys**.

#### Start a new key

Choose **New API key** and pick the **Environment**, for example **Development**.

#### Name it

Enter a **Name** of up to 60 characters, such as `CI pipeline`.

#### Pick scopes and expiry

Tick only the **Scopes** the key needs. Then choose an **Expiry**: **Never**, **30 days**, **60 days** or **90 days**.

#### Create and copy

Choose **Create key**, then copy the key into somewhere safe, such as your CI system's secrets.

![New API key dialog with the Environment, Name, Scopes checkboxes and Expiry fields](/_fern-files/_img/6aa3a0cb17a562ef10176a2e6d67d5c2d7b13cec963b748b61d9a3bff4e2d3fb.webp)

> **Warning**
>
> The key is shown only once. If you lose it, revoke it and create a new one.

#### What each scope allows

| Scope                                        | What the key can do                            |
| -------------------------------------------- | ---------------------------------------------- |
| **Session: Create**                          | Start agent sessions.                          |
| **Session: Read**                            | Read and follow agent sessions.                |
| **Session: Stop**                            | Stop, pause and resume agent sessions.         |
| **Session: Permissions**                     | Read and answer permission requests.           |
| **Session: Connect**                         | Open and refresh live connections to sessions. |
| **Project: Read metadata**                   | Read project and environment configuration.    |
| **Audit: Read logs**, **Audit: Tail stream** | Nothing yet. They're reserved for audit logs.  |

## Use a key

Send the key in the `Authorization` header of each request, as `Bearer <your key>`, to `https://us.api.aosplane.io`.

## Revoke a key

Choose **Revoke** on the key's row, then **Revoke key**. Anything using it loses access right away, and this can't be undone.

![API keys page listing keys with their environment, scope count, status, key prefix, created, last used and expiry dates](/_fern-files/_img/0b244a4b289038e9ca0d9c207e5d7243ee48bf2fb96a77f79e30c9d729c96b0b.webp)

## Good to know

* The list shows each key's first characters and its status: **Active**, **Expired** or **Revoked**.
* A key set to **Never** still expires after 90 days, so plan to replace keys regularly.
* Revoked keys are hidden until you turn on **Show revoked**.

## Related

* [Audit logs](/audit-logs)
* [Start a session](/start-a-session)