Machine identities + capabilities
How an AI agent or automated service authenticates to a hosted PolicyVault deployment, and how scopes narrow what it can do.
A machine identity is a credential an authenticated human wallet session creates for an automated caller — an AI agent, a bot, a backend service. It is a hosted-only concept: self-hosted deployments (a single trusted operator on loopback) have no notion of it, the same way they have no hosted sessions at all.
The model: a machine identity is exactly its creator, narrowed
A machine identity is bound to the wallet's own public key that created it (creatorXOnly). This means every existing tenancy and covenant check applies to it completely unmodified — a machine identity sees and can attempt exactly what its creating wallet could see and attempt, never more. Scopes then narrow further, on top of that: they restrict which specific API operations a given credential may attempt. Scopes can never widen what tenancy already allows.
Creating and rotating a credential
POST /api/v1/identities creates an identity and mints its first bearer credential in one call. The raw token is shown to you exactly once; only its hash is ever stored server-side. To rotate without downtime: mint a second credential, deploy it, then revoke the first — never revoke first.
Scopes (deny-by-default)
An unmapped route is refused for a machine principal by default — adding a new route later without explicitly classifying it leaves it unreachable by any machine identity until a human does. Representative scopes:
| Scope | Roughly gates |
|---|---|
read:vaults, read:requests, read:governance, read:risk, read:organizations, read:manifests, read:network, read:audit, read:metrics | The corresponding read-only routes |
request:build | Building/simulating a spend request |
request:sign, request:submit, request:reject | The corresponding request-lifecycle actions |
request:break-glass | Required in addition to request:build for ownerPause / ownerRecover — an API-surface conservatism on top of the covenant's own owner-signature requirement |
governance:propose / :approve / :cancel | The matching governance routes |
risk:release | Releasing a held risk-review evaluation |
organizations:manage | Mutating organization/member/assignment metadata |
What a machine credential can never do, regardless of scope
Identity management itself (/identities*) is refused for any machine credential no matter what scope it holds — this is a structural, wallet-session-only exclusion, not a scope you could grant. A token can never mint, widen, or revoke its own — or a sibling's — authority. The test-only dev-signer routes are similarly never reachable by a machine credential.
The token is never logged
The reference clients hold a bearer token behind constructs that make it structurally incapable of appearing in a log, a stack trace, a JSON.stringify, or a repr — this is not a redaction convention you have to trust; the value is simply never in a printable form.