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

# API Keys

> Create scoped keys for external systems.

API keys are workspace-scoped and act as the user who creates them. Agent access follows that user's current workspace, team, and agent permissions. Scopes limit available operations, and project or team allowlists narrow task, document, and file access where applicable.

## Create a key

1. Open the Erstan app.
2. Select the target workspace.
3. Open **Settings -> API Keys**.
4. Click **Create Key**.
5. Enter a descriptive name.
6. Select scopes and, for task, document, or file scopes, the matching project and team allowlists.
7. Copy the secret when it is shown.

The secret is only shown once. Erstan stores a hash of the key, not the raw secret.

## Scopes

| Scope             | Allows                                                                                                                                                                                                           |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agents:list`     | List the published agents the key creator can normally read.                                                                                                                                                     |
| `agents:read`     | Read accessible agent authoring state, drafts, the live node catalog, and the builder guide over MCP.                                                                                                            |
| `agents:write`    | Create drafts in accessible teams. Together with `agents:read`, update, validate, or revision-safely publish agents the creator can normally edit over MCP.                                                      |
| `agents:run`      | Start and continue published-agent runs. Together with both authoring scopes, test a manageable draft in Builder Preview. Includes explicit question replies and approval decisions.                             |
| `runs:read`       | Poll runs started by this key.                                                                                                                                                                                   |
| `tasks:execute`   | Read and manage complete Tasks, selectable relations, attachments/collaboration, lifecycle, and exact Task-linked runs in allowlisted projects and teams via the [MCP server](/developers/connect-coding-agent). |
| `documents:read`  | Read and search documents in allowlisted teams via the MCP server.                                                                                                                                               |
| `documents:write` | Create and edit documents in allowlisted teams via the MCP server.                                                                                                                                               |
| `files:read`      | List and read files in allowlisted teams via the MCP server.                                                                                                                                                     |
| `files:write`     | Create and update files in allowlisted teams via the MCP server.                                                                                                                                                 |

## Agent access

There is no per-key agent allowlist. All agent scopes use the key creator's current workspace, team, and agent permissions. Erstan rechecks membership and permissions on every request, so team or role changes take effect without rotating the key.

`agents:list` and `agents:run` expose only the retained published version. The MCP authoring scopes are intentionally different: `agents:read` can inspect accessible drafts, and `agents:write` can create a draft in an accessible team. Updating and validating saved agents require both authoring scopes plus the creator's normal edit permission.

Authoring keys should normally hold both `agents:read` and `agents:write`; scopes are exact and additive. MCP can validate and publish the exact current manageable draft with an opaque revision guard, but cannot archive or delete it. Add `agents:run` to use `test_agent` for a current-version-guarded Builder Preview run, and `runs:read` to poll that run. Published-agent execution remains separately gated by `agents:run`. Disabled agents remain authorable under normal permissions but cannot run through the published-agent path; archived agents cannot be authored. Removing the agent from the workspace or removing the creator's access makes it unavailable to the key.

## Allowed projects and teams

The task, document, and file scopes are gated by per-key allowlists (`allowedProjectIds`, `allowedTeamIds`):

* `tasks:execute` requires at least one allowed project or team. A task is reachable only when its project or team is on the key's allowlists.
* `documents:read` and `documents:write` require at least one allowed team. Documents are team-scoped, so project allowlists never grant document access.
* `files:read` and `files:write` require at least one allowed team. Files are team-scoped, so project allowlists never grant file access.

Allowlists fail closed. A key with these scopes but empty allowlists cannot be created, and anything outside the allowlists is invisible to the key. Key creation rejects IDs that do not exist in the key's workspace (`allowed_project_invalid`, `allowed_team_invalid`) and missing allowlists (`allowed_projects_or_teams_required`, `allowed_teams_required`).

Key list and detail responses include the `allowedProjectIds` and `allowedTeamIds` arrays alongside the existing fields.

## Expiry and revocation

Keys can have an optional expiry date. Workspace admins can revoke a key from **Settings -> API Keys**.

Revoked and expired keys return authentication errors.