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

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

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

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

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

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

Set an optional expiry

Optionally set an expiry date so the key stops working automatically after a chosen time.
5

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

​
Scopes

Scopes control what a key can do. Grant the narrowest set that covers your use case. 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.
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.
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.
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 and the connector’s write policy (Allow / Require approval / Deny). Actions that require approval still pause for a person to review.
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.

​
Expiry and revocation

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

Revoke from Settings → API Keys

Open Settings → API Keys, find the key by its name, and revoke it.
2

Rotate when needed

To rotate, create a new key, update your integration to use it, then revoke the old one.
Revoked and expired keys return authentication errors on every request. The runs they started before revocation are unaffected.

​
Next steps

Developer API: API keys

Full request and response detail for using keys programmatically.

Run agents via the API

Start runs and poll results from your own systems.

Build agents over MCP

Create, validate, test, and revision-safely publish drafts.

Preview, publish & versions

Publish an agent so a key can run it.

Security & write safety

How approvals and per-user authorization keep writes in your control.