Skip to main content

​
Scoped API Keys

A normal API key acts as you: it can read every dataset, drive agents, and mutate resources in any organization you belong to. That is the right shape for an operator credential and the wrong shape for a server that only needs to do one job — a portal backend that queries two datasets and writes rows into one should not hold a credential that can do everything else too. A scoped key is an erdo_api_* key minted with a capability allowlist and, optionally, a resource-slug allowlist. It authenticates exactly like a normal key, but it can only call the /v1 endpoints its capabilities map to, and (where slugs are given) only against the named datasets and workstreams. Everything else returns 403 permission_denied.

​
Read-only keys

A read-only key is the other way to narrow a key. Instead of naming capabilities, mint it with "access": "read". It can call every /v1 read endpoint in any organization you belong to and nothing that changes anything. Pass X-Organization-ID (or --org in the CLI) to choose the organization, exactly as with a normal key; your membership is checked on every request.
A read-only key may call:
  • every GET endpoint under /v1, except token management, managed organizations, integration connect links, the integration connection check and a single sending domain (both refresh state from the provider);
  • these read-only POST endpoints: dataset query and fetch (SQL runs read-only against the dataset’s database), emails-query, voice/widget-conversations, page-analytics/query, and lead-playbook/read-back.
It cannot start agent runs (/v1/ask, thread sends, query-nl), use /mcp, or mint keys. access cannot be combined with capabilities. GET /v1/tokens shows each key’s access.

​
Minting a scoped key

Mint from a session or a normal (unscoped) API key via POST /v1/tokens — a scoped key can never mint keys itself:
The raw key is returned once. List and revoke scoped keys exactly like normal keys: GET /v1/tokens (scoped keys carry is_scoped, capabilities, and resource_slugs) and DELETE /v1/tokens/{id}. A scoped key is pinned to the organization it was minted in. Its slug allowlist names resources within that org, so the key rejects any X-Organization-ID header that names a different organization — even one its owner belongs to.

​
The capability vocabulary

The vocabulary is small and closed — minting with any string not listed here is rejected: GET /v1/me works with any scoped key — it only echoes the caller’s own identity and org, and is the “does this key work” probe. Outreach deliberately does not inherit resources:write. Arming a batch can contact people and spend money, so a portal that drives it needs the explicit outreach:send grant. Every outreach request also requires a validated X-Project-ID; a capability never supplies or widens project scope.

​
Fail closed

Scoped keys deny by default:
  • An endpoint that is not explicitly mapped to a capability is unreachable — including endpoints added to /v1 after the key was minted, the /mcp endpoint, and the legacy SDK surface. New surface area never silently widens an existing scoped key.
  • Deliberately unmapped today: org-wide dataset listing and search (GET /v1/datasets, /v1/datasets-search) and ID-addressed dataset reads — a slug-confined key cannot enumerate or address datasets outside its allowlist.
  • When resource_slugs is non-empty, slug-addressed dataset and workstream calls outside the allowlist are denied even when the capability is granted.

​
What no capability can grant

Regardless of the capabilities a scoped key was minted with, it can never:
  • mint or manage credentials of any kind (/v1/tokens, scoped-token minting, the manager key),
  • touch managed-organization surfaces (create, revoke, adopt, or seat members),
  • connect or delete integrations, or create integration connect links.
These are hard-denied at the platform, so a leaked scoped key cannot escalate back to the full credential it was minted to replace.

​
Agent recovery

A resumed agent keeps the original key’s capabilities, slug restrictions and selected project. Recovery requires the same active key and unchanged configured restrictions, and cannot outlive the key’s original expiry even if that expiry is extended later. Current resource permissions still apply; a temporary verification failure can be retried. Revoked, expired or changed keys require a new explicitly authorized attempt; an approval cannot promote a scoped run into a full organization credential.