# Policies

Executive summary
**A policy defines the approval rules for a specific type of action: who must approve, how many approvals are needed, where the rule applies, and under what conditions.**

- Policies match intents by type and condition.
- `intentOrigin` separates normal user-signed proposals from API-only system-signed proposals.
- Workflows define approval roles, quorum, and sequence.
- Scope controls where the policy applies in the domain hierarchy.
- Rank determines priority when multiple policies could match.
- Missing or overly broad policies can either reject legitimate work or create security gaps.


Why this matters
Policies are the main control mechanism for custody operations. Well-designed policies enforce spending limits, require multi-party approval, route high-risk actions to senior reviewers, support compliance workflows, and create a governed path for changing the governance model itself.

## What is a policy?

A policy answers six questions:

| Question | Field | Example |
|  --- | --- | --- |
| What action? | `intentTypes` | `["v0_CreateTransactionOrder"]` |
| Which origin? | `intentOrigin` | `UserSigned` or `SystemSigned` |
| When? | `condition` | Amount above a threshold, trusted endpoint, author role. |
| Who approves? | `workflow` | Two operators, then one compliance reviewer. |
| Where? | `scope` | `Self`, `Descendants`, or `SelfAndDescendants`. |
| Which policy wins? | `rank` | Higher rank wins among matching policies. |


When an intent is submitted, the system selects the applicable policy and enforces its workflow.

## How policies are selected

Policy selection happens in this order:

1. **Filter by scope**: Find policies that apply to the target domain.
2. **Filter by intent type**: Keep policies whose `intentTypes` match the intent. If `intentTypes` is omitted, the policy can match all intent types.
3. **Filter by intent origin**: Keep policies whose `intentOrigin` matches how the proposal entered the system.
4. **Evaluate conditions**: Keep policies whose condition evaluates to `true`. A missing condition always matches.
5. **Select by rank**: Choose the highest-ranked matching policy.
6. **Apply workflow**: Require approvals from the selected workflow.


If no policy matches, the intent cannot execute.


```mermaid
flowchart LR
    Intent["Intent submitted"] --> Scope["Scope check"]
    Scope --> Types["Intent type check"]
    Types --> Origin["Intent origin check"]
    Origin --> Condition["Condition evaluates true"]
    Condition --> Rank["Highest rank selected"]
    Rank --> Workflow["Workflow enforced"]
```

## Intent types

Intent types identify the operation being proposed.

| Category | Examples |
|  --- | --- |
| 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 endpoint management | `v0_CreateAccount`, `v0_UpdateAccount`, `v0_CreateEndpoint`, `v0_UpdateEndpoint` |
| Transactions | `v0_CreateTransactionOrder`, `v0_CreateTransferOrder` |
| Compliance | `v0_ReleaseQuarantinedTransfers` |


Omitting `intentTypes` creates a catch-all policy. Use this only for deliberate fallback or emergency controls.

## User-signed and system-signed policies

Most policies govern user-signed proposals. If `intentOrigin` is omitted, the policy behaves as `UserSigned` and does not match system-signed proposals.

System-signed proposals are API-only. They are submitted without a client-side payload signature, signed by the platform internally, and matched only by policies with `intentOrigin: "SystemSigned"`.

| Policy origin | Matches user-signed proposals | Matches system-signed proposals |
|  --- | --- | --- |
| Omitted | Yes | No |
| `UserSigned` | Yes | No |
| `SystemSigned` | No | Yes |


Use system-signed policies narrowly. Specify explicit `intentTypes`, keep the scope deliberate, and use conditions that check the service submitter. For example:


```json
{
  "intentOrigin": "SystemSigned",
  "intentTypes": ["v0_CreateTransactionOrder"],
  "condition": {
    "expression": "submitter.type === 'Service' && submitter.custodyRoles.includes('gas-station')",
    "type": "Expression"
  }
}
```

Omit `workflow` only when automatic execution is intentional. If a system-signed policy includes a workflow, user-signed approvers must complete that workflow. System-signed approve and reject requests are not part of the API.

## Conditions

Conditions are JavaScript expressions that decide whether a policy applies.


```json
{
  "condition": {
    "expression": "context.request.payload.parameters.amount > 50000000000n",
    "type": "Expression"
  }
}
```

Use conditions to distinguish business cases:

- Transaction amount.
- Ledger or asset.
- Destination type.
- Endpoint trust score.
- Author role.
- Service submitter role or subject.
- Role being assigned.
- Time window.
- Compliance status.


Policy conditions can use `context.request` for the current intent and `context.references` for entities referenced by the intent. For the full JavaScript reference, see [Policy reference](/products/custody/governance/policies/reference).

## Workflows and quorum

Workflows define who must approve an intent.


```json
{
  "workflow": [
    { "role": "operator", "quorum": 1, "type": "RoleQuorum" },
    { "role": "compliance", "quorum": 1, "type": "RoleQuorum" }
  ]
}
```

| Workflow value | Behavior |
|  --- | --- |
| Omitted | Intent auto-approves. Use carefully. |
| Empty array `[]` | Intent auto-rejects. |
| Array with steps | Each step must be satisfied in order. |


For user-signed proposals, the maker's submitted intent counts as the first approval. If the first step requires `operator`, the maker must have `operator`. If the first step requires quorum `2`, the maker plus one other eligible user must approve.

For system-signed proposals, the service submitter proposes the intent but does not provide a user approval. Any approval workflow is completed by user-signed approvers.

Workflow objects:

| Type | Purpose |
|  --- | --- |
| `RoleQuorum` | Require approvals from users with one role. |
| `And` | Require both approval paths. |
| `Or` | Allow either approval path. |
| Sequential array | Require ordered approval stages. |


## Scope, governing strategy, and inheritance

Policy scope works with domain governing strategy.

| Scope | Applies to |
|  --- | --- |
| `Self` | Intents targeting the policy's own domain. |
| `Descendants` | Intents targeting child domains. |
| `SelfAndDescendants` | Intents targeting the policy's own domain and child domains. |


In a hierarchy, both target-domain policies and ancestor-domain policies may be relevant. The domain governing strategy decides how parent and child policies interact:

| Strategy | Behavior |
|  --- | --- |
| `ConsiderDescendants` | Parent and child policies can both be considered. |
| `CoerceDescendants` | Matching parent policies override child-domain policies. |


For domain behavior, see [Domains](/products/custody/governance/domains).

## Rank

Rank controls priority among matching policies. Higher rank wins.

Use rank intentionally:

- Higher rank for more specific, higher-risk cases.
- Standard rank for routine workflows.
- Low rank for catch-all fallback policies.
- High rank for emergency policies only when their intent types and scope are explicit.


## Breakglass policies

A breakglass policy provides an emergency path for exceptional scenarios such as court orders, urgent freezes, lost access, or recovery from misconfiguration.

Good breakglass policies have:

- Explicit intent types.
- Narrow scope.
- High quorum.
- Independent approvers.
- Clear operating rules.


Breakglass is not a substitute for normal policy design. It should be part of [Design your policies](/products/custody/governance/genesis/design-your-policies) and included in the launch review before running Genesis.

## Policy lifecycle

Policies are created, updated, locked, and unlocked through intents. Policy-management policies should be stricter than routine operational policies because they control how governance can change.

For operations, see [Manage policies](/products/custody/governance/policies/manage-policies). For examples, see [Policy examples](/products/custody/governance/policies/examples). For schema, workflow syntax, condition syntax, JavaScript rules, and common mistakes, see [Policy reference](/products/custody/governance/policies/reference).