Skip to main content

The Permission Model

One evaluator decides every request, whatever made it: a person, an API key, an agent, a trigger, a task, a tool server calling back. This page is the canonical statement of how authority is formed, stored and narrowed. Module pages keep their own specifics and link here.

Policy syntax, SRNs and conditions: IAM. Action strings: Permissions Reference.

Grant and cap​

A request's authority is its grant ∩ every cap, inside the project its credential is pinned to.

TermIsAbsent
GrantThe user's policies; a trigger's policy_ids for its firing; an agent's under run_as: agentAllows nothing
CapA key's policy_ids, an OAuth scope, an IAM token's bound, an On-Behalf-Of assertionNarrows nothing

A cap never adds: an Allow beyond the grant grants nothing. Default deny, an explicit Deny wins (Policy Evaluation). Every grant and cap is read at each request, so editing a policy or deleting a key takes effect on work already running.

Who a request runs as​

CredentialGrantCaps
Login (JWT)The user's policies; admin is unrestrictedNone
API keyIts owner's policiesThe key's policy_ids; pinned to its project_id
OAuth tokenIts user's policiesThe consented scope; pinned to its project
IAM tokenIts issuing key'sThe token's bound ∩ the key's policy_ids

Only a credential with no project and no policy_ids held by an admin is unrestricted. Details: Authorization Model, API Keys.

Ask the engine what the calling credential may do with POST /api/v1/iam/check:

soat check-iam-permission \
--action agents:CreateAgentGeneration \
--resource srn:proj_V1StGXR8Z5jdHi6B:agent:agent_V1StGXR8Z5jdHi6B

A resource that acts later​

An agent, trigger, webhook, playbook version, decider, eval, ingestion rule or memory rule acts after the write that made it, when nobody is present. It carries its own authority, policy_ids, so it survives its writer and never borrows the writer's credential at run time.

ResourceActs asCapped by whoever starts it
Agentrun_as: caller the caller; run_as: agent its policy_idscaller: yes. agent: no
TriggerIts policy_ids for a firing nobody calledA manual fire: the firer ∩ policy_ids
Playbook versionIts policy_ids (principal_type: playbook_version)No
Decider, evalIts policy_idsYes: the requester, the run's starter
Ingestion ruleIts policy_idsYes: whoever ingests
Memory ruleIts policy_ids alone (principal_type: memory_rule)No
WebhookIts policy_ids decide what a delivery may readNot applicable

What its writer must hold​

A resource does no more than whoever writes it. Every create and edit, through the API or a formation, is checked against the resource as the write leaves it, whichever fields the request names:

The resourceThe writer must holdRefusal
carries policy_idsevery grant of each policy, inside the resource's project403 POLICY_GRANT_NOT_HELD
starts a targetthe target's start action403 ACTION_NOT_HELD
names a secretsecrets:UseSecret on it403 FORBIDDEN

A builtin tool may name only what the deployment's builtin catalog offers: the native actions it allows, and the actions it adds. An added action holds its writer to the actions the deployment declares for it, and its server receives the call only with the signed assertion (What a tool server receives).

Start actions: agents:CreateAgentGeneration, tools:CallTool, deciders:CreateDecision, tasks:CreateTask, orchestrations:StartRun, evaluations:RunEval. Editing a policy a resource carries is attaching it again, and deleting one it names is 409 POLICY_HAS_DEPENDENTS. Full table: The writer rule.

An empty policy_ids allows nothing; a create without one is 400 VALIDATION_FAILED where it is required.

run_as​

An agent's run_as states what its policy_ids are.

run_asA turn runs asThe caller needs
caller (default)the caller, capped by policy_idseach permission the agent's calls perform
agentpolicy_ids alone, inside the agent's projectagents:CreateAgentGeneration on the agent

run_as: agent needs a non-empty policy_ids, else 400 AGENT_RUN_AS_REQUIRES_POLICIES. It lets an agent serve a caller that holds nothing else, such as an MCP client or a channel contact. The project's agent_policy_ids cap every turn in both modes. Details: Execution Identity.

soat create-agent \
--name support-agent \
--run-as agent \
--policy-ids '["pol_V1StGXR8Z5jdHi6B"]'

Stored authority​

Work that outlives its request stores the authority it was started under: the starter's grant and every cap on it, or a trigger's policy_ids for a firing nobody called. It stores policy ids and caps, never a token, so it does not expire and is read at every call.

WorkStoresEvery later drive runs under it
GenerationThe starter's, or the agent's under run_as: agentTool calls, submit-tool-outputs resumes
Approval continuationThe proposing generation'sThe approved action and later approvals of the chain; never the approver's
TaskThat of whoever last moved itDispatches; an automation hop carries the routing run's
Orchestration runThe starter'sEvery drive; loop and sub_orchestration children inherit it
Trigger firingThe trigger's policy_ids, or that ∩ the firer'sThe run or generation it starts; a redelivery too

Rules that hold for all of it:

  • A resume only narrows. Whoever resumes work holds the stored authority to their own: it can do only what both allow, and a wider resumer adds nothing. Under run_as: agent the agent's grant applies either way.
  • Revoking stops it. Deleting the starting key, or removing its permission, refuses the work's next call. Deleting a trigger refuses every call of work under it (403 FORBIDDEN).
  • Fail closed. Work that stores no authority, or whose authority names a user or API key that no longer exists, makes no call: 409 WORK_AUTHORITY_MISSING, on every path (a tool call, an in-process API call, a firing, a playbook execution).
  • Attribution. Records name the principal that acted (key_…, a trigger, a playbook version, a memory rule); acted_as on a generation says whose authority its tool calls ran as.

What the caller names​

Authority formed from the stored grant covers what the agent does. What a caller supplies in the call itself is the caller's: a document or tool_output message (every action a tool_output reaches), a per-call knowledge_config, a tool_context. It is checked as the caller, capped by policy_ids under run_as: caller, so naming a resource never reaches it through the agent's wider grant.

IAM tokens​

An API key scoped to a project issues a short-lived token that acts as the key held to a narrower policy, for a caller the key serves on behalf of someone with less reach. POST /api/v1/iam/tokens needs iam:CreateToken and answers 201 { "token", "expires_at" }.

soat create-iam-token \
--policy '{"statement":[{"effect":"Allow","action":["agents:CreateAgentGeneration"]}]}' \
--principal '{"type":"service","id":"billing-sync"}' \
--ttl-seconds 300
  • The bound is policy (inline) or policy_ids, exactly one. Work the token starts keeps the bound after the token expires; policy_ids are re-read, an inline policy is a snapshot.
  • ttl_seconds runs 30 to 900 (default 300).
  • Only a project-scoped API key issues one; any other caller is 403 IAM_TOKEN_ISSUER_NOT_ALLOWED.
  • principal is opaque and grants nothing; the audit log records it with the token's jti.

Full reference: IAM Tokens.

What a tool server receives​

An mcp tool call, and a call of an action the deployment adds to builtin, carries a signed assertion in X-Soat-Tool-Assertion. It names the tool, project, agent, generation and durable work that made the call, and carries the call's authority encrypted in ath: the receiver can read the identity claims and cannot read or alter the authority.

A tool server that writes back sends the assertion unchanged in X-Soat-On-Behalf-Of, with its project's API key or an IAM token that key issued. The request is then held to the key ∩ the authority the call was sent with ∩ the calling agent's policy_ids (and the generation's execution identity), and so is any work it starts. The assertion never widens: the principal stays the key.

An assertion that does not verify, names another project or carries no readable ath is 400 ON_BEHALF_OF_INVALID; nothing is written. Details: Tool Assertions, Writing on behalf of a tool call.

What mints no key​

A request narrowed beyond its credential's own grant creates no API key and consents to no OAuth client, because a key cannot carry the narrowing: an OAuth access token, an IAM token, an On-Behalf-Of assertion and every call durable work makes under its stored authority. POST /api/v1/api-keys, PUT /api/v1/api-keys/{id} and an api_key formation resource answer 403 CREDENTIAL_NARROWED. Reading, listing and deleting keys are unaffected. See A project-scoped token writes no key.

What an admission service may add​

A deployment may register an admission service for runtime writes it gates for its own reasons. It is asked after authorization allowed the write, before it executes, on every way in: REST, a builtin tool call and a formation create or update. A start (a generation, a run, a manual fire) is asked once, where a caller starts it; the run's own steps and a scheduled firing are not asked again.

  • It may refuse: the caller receives the service's own 4xx status, code, message and meta.
  • It may not allow: a write authorization refused is never asked about, and a service that does not answer refuses (502 ADMISSION_UNAVAILABLE).
  • It sees the write (action, project, resource, body as applied) and the principal; it grants nothing and its answer is not a policy.

Refusals​

Status and codeMeans
403 FORBIDDENThe grant or a cap denies the action; meta.denied_by names which
403 POLICY_GRANT_NOT_HELDA writer attaches a grant it does not hold; meta.ungranted
403 ACTION_NOT_HELDA writer names a target or action it may not start
403 CREDENTIAL_NARROWEDA narrowed request tried to create a key or consent to a client
403 IAM_TOKEN_ISSUER_NOT_ALLOWEDThe caller may not issue an IAM token
400 AGENT_RUN_AS_REQUIRES_POLICIESrun_as: agent without policy_ids
400 ON_BEHALF_OF_INVALIDThe assertion does not verify, names another project or has no ath
409 WORK_AUTHORITY_MISSINGDurable work stores no authority, or one that no longer resolves
409 POLICY_HAS_DEPENDENTSA policy a resource still names cannot be deleted
The service's 4xx and codeThe admission service refused the write
502 ADMISSION_UNAVAILABLEThe admission service asked about the write did not answer

The denial shape and the 403/404 split: What a Denial Looks Like.