API keys

Bearer tokens for apps, sites, scripts and AI agents that call your pod.

A key answers two questions:

• Which doors can it knock on? That is its scopes, a coarse gate per API surface.
• What can it touch once inside? That is its grant, fine-grained: kinds, actions, workspaces, projects, or single objects.

A key can never do more than the person it acts for. Effective access is always grant ∩ what you can see and do.

Creating a keyCopy Anchor Link

1. Open your pod's admin console (for example https://pod-admin.example.com) and go to Keys. A key for a single workspace is created from that workspace's API keys tab instead.
2. Click New key and name it after what will use it (for example "Portfolio site", "n8n").
3. Pick its scopes and its grant.

The key is shown once, so copy it immediately. Only a hash is stored.

For an AI agent, do not create a key by hand: synap connect <agent> (from @synap-core/cli) gives each agent its own key and identity. See Connect an agent.

To create one programmatically, call the tRPC procedure apiKeys.create. keyName, scope (at least one) and grant are required:

{
  "keyName": "Portfolio site",
  "scope": ["hub-protocol.read"],
  "expiresInDays": 90,
  "grant": {
    "permissions": ["entity.portfolio.read", "document.read"],
    "workspaceIds": ["<workspace id>"],
    "label": "Portfolio site"
  }
}

Grants: what a key may touchCopy Anchor Link

A grant is a list of permissions plus optional resource sets. Permissions use the same keys as Synap's governance events, with an optional kind in the middle:

<subject>[.<kind>].<action>

Matching is segment by segment. * stands for one segment, and a shorter permission covers everything under it: entity.knowledge covers entity.knowledge.read and entity.knowledge.update. There is no partial-word wildcard.

Resource sets narrow further. Leave a set out for no narrowing on that axis.

How it is enforced:

• Reads are filtered in the pod's access layer, so a key with entity.portfolio.read simply never sees other kinds.
• Writes are checked at the governance gate before anything else. A write outside the grant is refused, never queued for approval.
• A grant permits, it never auto-approves. Agent writes still go through proposals as usual.
• A write that creates related objects (links, files) needs those subjects in the grant too.
• A key with no grant keeps the older behaviour: its scopes plus everything you can see.

Doors a scoped key can read throughCopy Anchor Link

A key whose grant is narrower than * can only read through doors whose reads the grant actually bounds. Every other read door answers 403 GRANT_DOOR_UNSUPPORTED; doors are added as they are migrated.

GET /entities without q and GET /webhooks are open to scoped keys on releases after v1.1.3.

Doors that combine several kinds of record (POST /knowledge/search, /knowledge/ask, /knowledge/answer, /entities/retrieve and /memory/search, and MCP read tools such as synap_ask, synap_orient and synap_find) cannot filter row by row yet. A scoped key passes one only when its grant reads every kind of record the door reads, with no workspace, project or object limit. Every other read door (for example the REST graph, events and runs) needs a key with the full-access * grant.

Writes go through to the governance gate, which applies the grant. On releases after v1.1.3, two kinds of write need a key with unrestricted * (no workspace, project or object limit): doors that act on everything the person owns and that no grant can narrow (for example the calendar feed URL, connector credentials and disconnection, and deleting a vault secret), and, on the tRPC bridge, mutations the gate cannot bound yet.

Access roles: reusable grantsCopy Anchor Link

Save a grant under a name in the Browser app (Settings → AI → Access roles), or with Save as role in any access editor. The next key, app or agent can start from it.

• A role is a template. A key made from a role keeps what the role said at that moment. Editing the role later never changes an existing key.
• The key remembers which role it came from. Pass grant.roleId when minting through the API; it must be one of your own roles.
• Only you can create or change your roles. Your agents can list them but never edit them.

Limiting an agentCopy Anchor Link

An agent's capabilities use the same permission keys. In the agent's panel, the same editor limits what it may change, down to one kind (entity.knowledge.update). An agent can always read what you can read, so the read column is shown on and locked. Leaving every box unticked makes the agent read-only. It never reverts to full access.

LifetimeCopy Anchor Link

expiresInDays sets how long a key lives:

Rotating a CLI key keeps its remaining lifetime.

Key formatsCopy Anchor Link

The prefix tells you what kind of key it is:

Scopes: which surfaces a key can callCopy Anchor Link

Older keys may still carry retired scopes (preferences, notes, tasks, …). No door ever checked them, and new keys cannot be minted with them.

Workspace-bound keysCopy Anchor Link

A key created for one workspace (from that workspace's settings, or with a workspaceIds grant) is confined to it. A request for another workspace is refused with 403.

Using a keyCopy Anchor Link

Pass it as a Bearer token:

curl https://pod.example.com/api/hub/entities \
  -H "Authorization: Bearer synap_user_..."

A key works on the Hub REST API, MCP and the other doors its scopes name. It does not work on /trpc, the endpoint the SDK calls: that endpoint accepts only a sign-in session. See SDK first query.

Seeing and revoking keysCopy Anchor Link

My connections (in the pod admin console's account menu) lists the keys you hold and the keys your agents and apps hold for you, and you can revoke either kind there. Each key shows what it may touch, e.g. "Read Portfolios, Documents · 1 Space". Revoking takes effect immediately: in-flight requests with that key get 401.

Security notesCopy Anchor Link

• Keys are hashed at rest. The pod never stores the plaintext.
• An AI agent's key cannot mint keys for other agents, widen its own approval rules, or grant itself vault access. Those requests are refused or become proposals you approve.
• Keep keys in environment variables, one key per integration, with the smallest grant that works.

Next stepsCopy Anchor Link

• Hub REST API reference: every route a key can call
• Scripts and agents with an API key: the TypeScript client
• Webhooks
• Connect an agent