Identity and access

Identity answers who is acting. Access answers whether that actor may perform this action now. Tanomis keeps the two apart: an identity mode declares the posture an agent intends, the authorization path narrows what any credential may carry, and the target resource makes the final decision.

At a glance

• Two identities on every request: the invoking principal (person or service, from the token) and the agent actor (the version, attested by the platform).
• An agent’s identity mode declares its posture; its scope ceiling is the most authority its own tokens can ever carry.
• Authority only narrows: brokers intersect, they never widen. Delegated authority is what was granted for the call, not the agent’s registered envelope.
• The evidence records both identities, so an auditor can see who asked and which version acted.

Availability: Service-mode bind-time identity is enabled per tenant by a platform operator; where it is off, the session runs without an identity assertion. Scoped and delegated authority are held contracts: a public runtime workflow for scoped service API authority is not currently exposed. See What is available where.

Read the posture. Check the availability.Contract model, not a token setup guide

Service

Bind-time identity is conditional

Actor

Stable agent machine principal

Credential path

Per-bind agent identity assertion

Grant rule

Runtime requests no resource or scopes today

Not run-bound; a warm process can reuse it until expiry

Delegated

Contract defined; production path held

Actor

Intended: user subject plus agent actor

Credential path

Intended on-behalf-of credential

Grant rule

Intended to fit both agent ceiling and user entitlement

No generally supported tenant-bound, agent-attributed exchange yet

Hybrid

The invocation chooses the path

Actor

Service actor or intended delegated pair

Credential path

One credential path per invocation

Grant rule

Apply the checks for the path that was chosen

Bind-time identity is conditional; both scoped authority paths are held

Chosen path

1. 1Requested actionConcrete scopes and an optional target audience
2. 2Effective ceilingBroker-cached authorization contract; 30-second TTL
3. 3Principal entitlementDelegated design only; live path is held
4. 4Delegated approval classificationAutonomous acquisition currently skips this check
5. 5Target authorizationAfter issuance, the resource decides the action

• Identity establishedPer-bind assertion; not scoped authority or proof of one run
• Approval requiredNo authority; token-exchange completion is not yet supported
• DeniedReturn the failing decision boundary

Service (conditional): the stable agent machine principal can receive a per-bind identity assertion with no resource or scopes; it is not run-bound, and scoped service API authority has no supported public runtime path. Delegated (held): the contract intends a user subject plus agent actor and an on-behalf-of credential, but no generally supported tenant-bound, agent-attributed production exchange exists yet. Hybrid (conditional): bind-time identity is conditional, while both scoped authority paths are held; one credential path is intended per acquisition and authority is never combined. If a future supported flow requests scoped authority, the contract model applies an effective ceiling and any supplied target audience. Approval classification is delegated-only, has no supported completion path, and autonomous acquisition skips it. The authorization contract can remain cached for up to 30 seconds.

Declaring an identity mode, scope, audience, model, or tool is never a grant. Each declaration is a ceiling, posture, or request that a later enforced decision can narrow or refuse.

How a request is resolved

Four things turn a request into an authorized action, in this order: CLI context → authenticated principal → selected workspace projection → organization + tenant.

1. A CLI context is local configuration: a named target environment plus its authentication state. It is not an organization or tenant.
2. The credentials identify the authenticated principal: the user, service, or agent whose authority bounds the request.
3. Workspace discovery returns only the projections granted to that principal. A selected workspace combines one organization, one attached tenant, the caller’s role, and effective capabilities.
4. The organization and tenant in that projection scope the resources the request may touch.

Selecting a workspace supplies request context; it does not create a resource or widen the caller’s grants. The API’s X-Organization-ID and X-Workspace-Tenant-ID headers select one granted projection; despite its compatibility name, X-Workspace-Tenant-ID carries the selected tenant ID. See Platform API request basics.

Two identities on every run

The invoking principal starts the request: a signed-in person, a backend with an automation client, or another agent. The selected workspace supplies the organization and tenant that principal may use.

The agent actor is the version that does the work. Where service-mode identity is enabled, the session bind also establishes a stable machine identity for the agent process. The session records the immutable execution version regardless.

Question	Answer today
Who selected the organization and tenant?	The invoking principal and its selected workspace.
Which code is running?	The immutable version and tenant enablement bound to the session.
Which identity can be established at bind?	The stable agent machine principal. Its assertion has no resource or scopes and is not proof of one run.
Which ceiling would a scoped request use?	The agent’s broker-cached authorization contract, not the session’s execution version. No public runtime flow makes that request today.
Was the final action allowed?	The target resource’s own authorization result, never the manifest or token alone.

Delegated and hybrid modes describe an intended model in which a user remains the subject and the agent is verifiably attributed as the actor. Do not describe a delegated token or audit entry as a verified on-behalf-of chain until a supported flow says it is.

Identity modes

Hosted manifests must declare one mode:

identity_mode: service
inherits_user_permissions: false

Mode	Intended authority	Availability
service	The agent’s own machine principal.	Bind-time identity is enabled per tenant and can degrade to a session without an assertion. The runtime requests no scoped API authority.
delegated	A user subject with the agent verifiably attributed as actor.	Contract-defined; the tenant-bound, agent-attributed exchange is held. Autonomous acquisition is rejected.
hybrid	Service or delegated authority, one credential path per acquisition.	Bind-time identity is conditional; both scoped authority paths are held. The two authorities are never unioned.

identity_mode is pinned by the agent’s first non-rejected version and must stay the same across later versions; a rejected first attempt does not pin it. A different trust model is a different agent. inherits_user_permissions: true is valid only with delegated or hybrid, and opts the version into an impersonation approval gate before it can become serveable; passing that gate does not make the held delegated flow available.

What the service assertion is, and is not

When enabled and established at session bind, service-mode identity asks for no target resource and no scopes. The result is an identity assertion, not a scoped API credential. The runtime injects it into the agent process and records the returned stable fingerprint on session-start evidence; a warm process can reuse the assertion until it expires, so it does not prove which run presented it. A record without the fingerprint means no identity was established for it; historical records are not backfilled.

The manifest still declares policy.scope_ceiling and policy.allowed_audiences as the agent’s authorization contract. A future supported flow would fit requested scopes to that ceiling and check a target audience. Today, the shipped runtime request supplies neither, no public workflow accepts a scoped service-token request, and autonomous acquisition does not evaluate approval sensitivity rules. The intended delegated design adds that effective scopes also fit the user’s entitlement, one acquisition uses one user-backed credential path, and the credential and evidence preserve the user subject and verified agent actor. The hosted exchange currently defers user-entitlement intersection to identity-provider issuance, so requested scopes are not proof of effective scopes; the complete path is held, and its approval-required response has no durable approval ID, decision endpoint, or resume path. Durable runtime questions and tool decisions are a separate, supported mechanism.

Do not infer scoped API authority from a service identity token, call an internal token endpoint, or build an approval UI from these concepts. Keep final action authorization at the target resource.

Changing a version’s authorization

A version’s manifest is immutable; to change scope_ceiling, allowed_audiences, or approval thresholds, register a new version. The scoped-authorization contract has its own clock: where the internal broker exercises it, it reads the agent’s effective registered manifest through a 30-second in-process cache, not the session’s execution version. A registration can change that contract before the new version receives traffic, and rolling execution traffic back does not necessarily restore the earlier contract. Review authorization impact at registration time and verify the effective contract after a change; use Roll out and roll back to move traffic, not as an authorization rollback.

Three controls, three questions

Control	What it bounds
policy.scope_ceiling	Concrete authority a minted agent token may carry.
permitted_models	Which model a run may select.
Integration tools.allow	Which published-contract tools the agent requests; current workspace access is checked separately.

Adding an mcp:... scope does not approve a connector tool, and adding an llm:... scope does not replace the model allowlist. See the connector authority gates.

When it stops

When	Typical reason	What to do
Validate or deploy	Unknown mode, wildcard grant, missing audience for a non-empty ceiling, or inherits_user_permissions with service mode.	Correct the manifest before publishing.
Register a later version	Its identity_mode differs from the pinned mode.	Keep the mode, or create a separate agent.
Establish bind-time identity	Identity is disabled, fails softly, or is denied in enforce mode.	An absent fingerprint is the visible no-identity result; confirm tenant configuration with your platform operator.
Authorize the final action	The target resource rejects the token or operation.	Inspect that resource’s policy outcome. A declaration cannot override it.
Design scoped or delegated API authority	You need a public scoped token flow, tenant-bound delegation, or approval completion.	The public path is held. Wait for a supported integration guide.

Treat an infrastructure error separately from a policy denial, and never widen the manifest to get past a transient failure.

Reading attribution

The Console’s agent identity view shows the stable non-secret fingerprint, pinned mode, provisioning state, ceiling, and allowed audiences. It never shows the identity provider’s principal reference or a client secret. Session and ledger evidence identify the agent and version and include the fingerprint when an identity was established. Session views describe the recorded subject plus the configured posture; they do not prove a fully persisted delegation chain. The tanomis session run command intentionally prints session and run identifiers and agent output, not machine-identity fields. Never copy a provider client ID, secret, or internal token into application logs.

Backend and CI identity

An automation client identifies the backend or pipeline making a platform request. It is separate from the identity an agent uses while running. Owners and admins choose its permissions; the platform checks its live state and tenant membership on every decision, so disabling the client or removing a scope applies without waiting for a token to expire.

Where to go next

• Agent manifest: the identity and policy fields.
• Sessions and runs: the durable session and each admitted run.
• Policy, approvals, and evidence: where identity sits among the controls.