An intent is a governed proposal to change the system. Every governed modification must go through the intent workflow before execution.
- Intents are immutable after submission.
- User-signed intents are signed by the proposer.
- API-only system-signed intents are submitted without a client-side signature, then signed by the platform before policy evaluation.
- Policies determine which additional approvals are required.
- Authorized checkers can approve or reject.
- Completed intents create an auditable record of governance decisions.
Intents are the enforcement mechanism for governance. Transfers, policy changes, user changes, domain changes, and many administrative updates flow through this model. This gives operators and auditors a complete record of who proposed a change, which policy governed it, who approved or rejected it, and whether it executed.
An intent represents a proposed change that:
- Is signed by the proposer, or is system-signed after API authentication.
- Has an operation-specific payload.
- Targets a domain.
- Expires if not approved in time.
- Executes only after the selected policy workflow is satisfied.
Most workflows use user-signed intents. The proposer authenticates, signs the request body with their registered private key, and the signature is verified before policy evaluation.
System-signed intents are available only through the API. A service caller authenticates with a bearer token and submits a SystemSigned request body without an author field or top-level signature. The platform signs the proposal internally, then policies with intentOrigin: "SystemSigned" decide whether the proposal is allowed. Even when system-signed intent configuration is enabled by default at deployment level, proposals remain disabled until the Gateway public signing key is registered in Notary and NOTARY_SYSTEM_SIGNED_INTENTS_ENABLED is set to enabled: true. For request details, see Intent request structure.
| State | Description |
|---|---|
| Proposed | Intent has been accepted for policy evaluation. |
| Pending approval | Intent is waiting for additional approvals. |
| Approved | Required approvals have been collected. |
| Executed | The change has been applied. |
| Rejected | An approver rejected the intent. |
| Expired | The approval window passed before completion. |
| Actor | Responsibility |
|---|---|
| User maker | Creates and signs a user-signed intent. The maker's signature counts as the first approval. |
| Service submitter | Submits a system-signed proposal with the API. The service submitter is recorded by subject, not by user ID. |
| Checker | Reviews, approves, or rejects according to the policy workflow. Approvals and rejections remain user-signed. |
For user-signed intents, the maker must have a role that satisfies the first policy workflow step. The maker cannot provide another approval for the same workflow.
For system-signed intents, the service submitter can propose only intent types admitted by a matching SystemSigned policy. If the selected policy has an approval workflow, user-signed approvers complete that workflow.
| Category | Example intent types |
|---|---|
| Domain management | v0_CreateDomain, v0_UpdateDomain, v0_LockDomain, v0_UnlockDomain |
| User management | v0_CreateUser, v0_UpdateUser, v0_LockUser, v0_UnlockUser |
| Policy management | v0_CreatePolicy, v0_UpdatePolicy, v0_LockPolicy, v0_UnlockPolicy |
| Account and vault management | v0_CreateAccount, v0_UpdateAccount, v0_CreateVault, v0_UpdateVault |
| Endpoint management | v0_CreateEndpoint, v0_UpdateEndpoint |
| Transactions | v0_CreateTransactionOrder, v0_CreateTransferOrder |
| Compliance | v0_ReleaseQuarantinedTransfers |
For complete payload structure, see Intent reference and Intent request structure.
Every intent has an expiry time. If the required approvals are not received before expiry, the intent does not execute and must be recreated if still needed.
An intent targets a domain. Users can target their own domain and, where governance allows, descendant domains. Users cannot target parent or sibling domains directly.
Dry runs validate a payload before live submission. Use dry runs for:
- Policy changes.
- Domain changes.
- User and user role-assignment changes.
- High-risk transactions.
- Any payload where condition or workflow behavior is uncertain.
For operations, see Manage intents and approvals.