Skip to main content
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

​
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.