# Intents and approvals

Executive summary
**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.


Why this matters
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.

## What is an intent?

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](/products/custody/v1.36/governance/intents/intent-request-structure#system-signed-proposal-request-body).

## Intent lifecycle


```mermaid
stateDiagram-v2
    [*] --> Proposed: Submit intent
    Proposed --> PendingApproval: Policy workflow applies
    PendingApproval --> Approved: Required approvals received
    PendingApproval --> Rejected: Approver rejects
    PendingApproval --> Expired: Expiry time passes
    Approved --> Executed: System applies change
    Executed --> [*]
    Rejected --> [*]
    Expired --> [*]
```

| 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. |


## Maker-checker model

| 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. |



```mermaid
sequenceDiagram
    participant Op as Operator
    participant Sup as Supervisor
    participant Comp as Compliance
    participant Sys as System

    Op->>Sys: Propose transfer intent
    Sup->>Sys: Approve
    Comp->>Sys: Approve
    Sys->>Sys: Execute intent
```

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.

## Intent types

| 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](/products/custody/v1.36/governance/intents/reference) and [Intent request structure](/products/custody/v1.36/governance/intents/intent-request-structure).

## Intent expiry and targeting

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

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](/products/custody/v1.36/governance/intents/manage-intents-and-approvals).