> ## 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 API keys for published agent runs and draft authoring.

API keys let systems outside Erstan — an MCP client, a NetSuite SuiteScript, a webhook, a scheduler, or your own backend — work with scoped Erstan capabilities. They can run published agents or create and update Agent Builder drafts. Each key is scoped to one workspace and acts with the key creator's current permissions.

<Info>
  This page covers the admin view: what keys are, how to create one, and how to revoke it. For request and response detail — endpoints, headers, payloads, and error codes — see the [Developer API](/developers/api-keys).
</Info>

## What an API key is for

A key is a credential an external system sends with each request so Erstan knows who is calling and what they may do. Keys are useful when you want to:

* Trigger an agent from another system (for example, run an invoice-triage agent when a record is created in NetSuite).
* Let a scheduled job or webhook start runs without a person signing in.
* Poll a run you started programmatically to read its result.
* Let an external MCP client create, inspect, update, validate, test, and publish Agent Builder drafts through guarded tools.

A key never grants access that its creator does not already have. Published-run scopes use agents the creator can access; authoring scopes can read visible agents, create drafts in accessible teams, and update only agents the creator can edit. Erstan checks the creator's current membership and permissions on every request.

<Note>
  `run_agent` runs only an agent's retained **published version**. The separately gated `test_agent` tool can run the current manageable draft in Builder Preview when the key also has both authoring scopes and `agents:run`. It uses real tools and normal approval policies. Archived agents cannot run; disabled agents cannot run through the published-agent path. See [Preview, publish & versions](/agents/publish-lifecycle).
</Note>

## Create a key

Creating and managing keys is an admin task. Open the workspace whose agents you want to expose, then create the key from Settings.

<Steps>
  <Step title="Open Settings → API Keys">
    In the target workspace, go to **Settings → API Keys**. Make sure you are in the right workspace — keys only ever work against the workspace they were created in.
  </Step>

  <Step title="Create a key and name it">
    Click **Create Key** and enter a descriptive name (for example, `NetSuite invoice intake`). The name is how you will recognize the key later when you need to revoke it.
  </Step>

  <Step title="Choose scopes">
    Select what the key is allowed to do. Scopes are additive — grant only what the caller needs. Agent scopes use your current access automatically; task, document, and file scopes also ask you to choose their project or team restrictions.
  </Step>

  <Step title="Set an optional expiry">
    Optionally set an expiry date so the key stops working automatically after a chosen time.
  </Step>

  <Step title="Copy the secret">
    The secret is shown **once**, at creation. Copy it and store it in your system's secret manager before you close the dialog.
  </Step>
</Steps>

<Warning>
  The full secret is displayed only at creation and cannot be retrieved again. Erstan stores a hash of the key, not the raw secret. If you lose it, revoke the key and create a new one.
</Warning>

## Scopes

Scopes control what a key can do. Grant the narrowest set that covers your use case.

| Scope             | Allows                                                                                                                                                                                 |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agents:list`     | List the published agents the key creator can normally read.                                                                                                                           |
| `agents:read`     | Read accessible agent drafts, the live node catalog, and Agent Builder guidance 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.                                                              |
| `runs:read`       | Read (poll) the status and result of runs this key started.                                                                                                                            |
| `tasks:execute`   | Let an external coding agent read and manage complete Tasks, selectable relations, attachments/collaboration, lifecycle, and exact Task-linked runs in allowlisted projects and teams. |
| `documents:read`  | Read and search documents in allowlisted teams.                                                                                                                                        |
| `documents:write` | Create and edit documents in allowlisted teams.                                                                                                                                        |
| `files:read`      | List and read files in allowlisted teams.                                                                                                                                              |
| `files:write`     | Create and update files in allowlisted teams.                                                                                                                                          |

A typical "run an agent and read its result" integration uses `agents:run` and `runs:read` together. A practical Agent Builder integration uses both `agents:read` and `agents:write`, because updates, validation, and publishing require both exact scopes; `agents:write` alone can only create drafts. Add `agents:run` to test drafts and `runs:read` to poll those tests. Task, document, and file scopes require project or team allowlists on the key; agent scopes use the creator's live Erstan permissions instead.

## Agent access

Agent access does not use a separate per-key allowlist. It follows the key creator's current workspace membership, team access, and agent permissions. Changing the creator's access immediately changes what the key can read, edit, or run without recreating the key.

<Warning>
  MCP cannot archive or delete an agent. Publishing requires both authoring scopes, the latest opaque revision, and an explicit `publish_agent` call. Draft testing requires `agents:read`, `agents:write`, and `agents:run`, executes real tools, and preserves normal approval policies.
</Warning>

<AccordionGroup>
  <Accordion title="What happens if an agent or the creator's access changes">
    If an agent has no published version, is disabled, archived, or removed from the workspace, the key can no longer run it. A disabled agent can still be authored by a creator with normal permission; an archived agent cannot. The same access checks apply when the creator loses access to that agent or team. Publishing restores run availability only when the creator can still access the enabled agent.
  </Accordion>

  <Accordion title="Do keys bypass NetSuite write approvals?">
    No. A key starts an agent run; it does not change how that agent's write actions are governed. NetSuite still uses [per-user authorization](/connectors/netsuite-authorize) and the connector's [write policy](/connectors/netsuite-manage) (Allow / Require approval / Deny). Actions that require approval still pause for a person to review.
  </Accordion>
</AccordionGroup>

<Warning>
  Treat a key like a password. Anyone holding it can use its scopes with the creator's current access — including running agents that write to NetSuite. Store it in a secret manager, never in client-side code or a public repository, and use a separate key per integration so you can revoke one without affecting the others.
</Warning>

## Expiry and revocation

Keys can have an optional expiry date, after which they stop working. You can also revoke a key at any time.

<Steps>
  <Step title="Revoke from Settings → API Keys">
    Open **Settings → API Keys**, find the key by its name, and revoke it.
  </Step>

  <Step title="Rotate when needed">
    To rotate, create a new key, update your integration to use it, then revoke the old one.
  </Step>
</Steps>

Revoked and expired keys return authentication errors on every request. The runs they started before revocation are unaffected.

## Next steps

<CardGroup cols={2}>
  <Card title="Developer API: API keys" icon="key" href="/developers/api-keys">
    Full request and response detail for using keys programmatically.
  </Card>

  <Card title="Run agents via the API" icon="play" href="/developers/run-agents">
    Start runs and poll results from your own systems.
  </Card>

  <Card title="Build agents over MCP" icon="workflow" href="/developers/build-agents">
    Create, validate, test, and revision-safely publish drafts.
  </Card>

  <Card title="Preview, publish & versions" icon="rocket" href="/agents/publish-lifecycle">
    Publish an agent so a key can run it.
  </Card>

  <Card title="Security & write safety" icon="shield" href="/security/overview">
    How approvals and per-user authorization keep writes in your control.
  </Card>
</CardGroup>