# Identity and access

Who asked, who acted, and how a request is resolved. The identity postures an agent can declare, what the platform actually establishes today, and why a declaration never grants 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.

- 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](/reference/availability).

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](/api#request-basics).

## Two identities on every run

The **invoking principal** starts the request: a signed-in person, a backend with an
[automation client](/guides/deploy/automation-credentials), 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:

```yaml
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](/guides/run/approval-required-actions) 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](/guides/deploy/rollout-and-rollback) 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](/guides/connect-tools/mcp-connectors#read-the-four-independent-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](/guides/deploy/automation-credentials) 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](/reference/agent-manifest#attribution-and-identity): the identity and policy
  fields.
- [Sessions and runs](/concepts/sessions-and-runs): the durable session and each admitted run.
- [Policy, approvals, and evidence](/concepts/governance): where identity sits among the controls.