Get started

Authentication

Keys are minted in the Dev tab of the app by workspace owners, admins and analysts. Each key is bound to the member who created it and to exactly one workspace.

Send the key in either header. Both are equivalent.

Authorization: Bearer ghost_...
# or
X-Api-Key: ghost_...

The workspace comes only from the verified key - it is never read from input. On every request the server re-checks that the key is enabled, that its owner is still a member, and that workspace API access is on. A revoked key, a departed member or a paused workspace loses access on the next call.

Scopes

Scopes are selected when a key is created and are independent - none implies another, including admin. Select each grant the integration needs. Workspace role restrictions apply on top: an admin-scoped key does not make its owner a workspace administrator. The /compute/* refresh endpoints require both the admin grant and owner/admin membership; graph.agent_run instead permits owners, admins and analysts with graph:read, graph:write and research:run.

graph:readRead graph data, sources, context, definitions, values, and modules.

graph:writeApply explicit account/contact edits without a model call; edit context, definition values and relations. Field and role restrictions still apply.

crm:readRead live CRM companies, contacts, deals and custom properties for validation; does not grant CRM writes.

crm:writePrepare and approve CRM changes under workspace policies; does not imply the independent live-read grant.

workflows:readRead visible workflows, runs, outputs, and schedules.

workflows:runCreate, edit, run, and schedule workflows; review gates.

research:runRun web research and Ghost-managed AI analysis. Additional usage charges may apply.

enrichment:runDiscover and enrich accounts and people. Provider charges may apply.

adminCreate and edit definitions, manage modules and use /compute/* refreshes with an owner/admin workspace role. Not required for graph.agent_run and does not grant other scopes or change membership.

Who can do what

RoleMint keysGrant adminSees keys

Owner / adminYesYesEvery workspace key

AnalystYesNoOnly keys they created

MemberNoNoNone

New grants are never silently added to existing keys. Live CRM validation needs explicit crm:read; crm:write is independent. Workflows:run separately authorizes approved automation and may include CRM effects; review its definition and destinations.

Change an existing key's grants

A Ghost system administrator can update a specific existing developer API key's grants in place through an audited operator change. The key secret stays the same; rotation is not required just to add or remove a grant. The current Dev UI supports creating and revoking keys, not editing grants, and there is no public API endpoint for a key to change its own permissions. Give the administrator the workspace, key name or ID, and exact grants to add or remove; never send the key secret.

After an update, GET /me returns the current grants and workspace role, and GET /capabilities shows authorization for catalog operations. The server reads current grants on each request and revalidates queued execution; removing a grant does not undo effects already applied. Changing key grants does not change workspace membership.