> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anchorage.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Policies and approvals

> Register approval keys, write policies that govern withdrawals and other changes, and endorse the actions those policies open.

The policy engine lets you decide, in code, which changes on your accounts go through on their own, which need sign-off, and which are refused. You register approval keys, write policies as boolean trees, and endorse the actions that open when a policy needs more signatures.

## What's available

| Action | Status | Notes |
| :- | :- | :- |
| Register and list approval keys | Live | |
| Create, read, and archive policies | Live | |
| Approval groups | Under construction | Returns mocked data only |
| Endorsements | Under construction | Returns mocked data only |

The engine is enabled per sandbox organization. Until it's enabled for yours, the policy endpoints return mocked data only.

Today you can register keys and create, read, and archive policies, and the engine evaluates them. Enforcement on withdrawals is being connected and isn't active in the sandbox yet, so a withdrawal isn't held or refused by a policy for now. When it is, `allow` and `deny` policies take effect as written. An `approvals` policy can be written now, but until approval groups and endorsements ship there is nobody to endorse, so a change it governs is refused rather than held.

## How it works

**1. Register approval keys**

Nominate existing Anchorage Digital API keys as approvers. No key material is generated or held for you.

**2. Group keys**

An approval group is a named set of keys. It means nothing on its own. It takes on meaning once a policy points at it.

**3. Write policies**

A policy targets resources and action types, applies when its conditions match, and says what a matching change needs: nothing (`allow`), endorsements from groups (`approvals`), or refusal (`deny`).

**4. Changes are evaluated**

Every governed change is checked against the active policies that apply. The engine denies by default: a change no policy governs is refused, an allowed change takes effect at once, and a `deny` anywhere refuses it outright.

**5. Endorsements are collected**

When a change needs more sign-off, an action opens and comes back on the `202`. Approvers endorse it until the tree is satisfied.

Your integration never creates an action directly. Policy evaluation does.

## Permissions

The policy engine endpoints don't use the permission names the account endpoints use. Your key needs `MANAGE_IAAS_POLICY_ENGINE` to write and `READ_IAAS_POLICY_ENGINE` to read. Ask your Anchorage Digital representative to add them to your key.

## Policy anatomy

| Field | Required | Description |
| :- | :- | :- |
| `name` | Yes | A human-readable name |
| `description` | No | What the policy is for |
| `target` | Yes | Which resources and action types it governs |
| `conditions` | No | When it applies. Omit to apply to every change hitting `target`. |
| `requiredActions` | Yes | What a matching change must satisfy |

### Target

| Field | Description |
| :- | :- |
| `resourceType` | `ACCOUNT`, `POLICY`, `KEY`, or `APPROVAL_GROUP`. Which family of action types the policy governs, and which kind of ID `resourceIds` holds. |
| `resourceIds` | Lowercase hyphenated UUIDs, at least one. For a creation action type, the top-level account IDs the policy governs. |
| `actionTypes` | The action types governed, all from the same family |

| Family (`resourceType`) | Action types | `resourceIds` name |
| :- | :- | :- |
| `ACCOUNT` | `WITHDRAWAL`, `DEPOSIT`, `TRUSTED_DESTINATION_ADD`, `TRUSTED_DESTINATION_REMOVE` | Accounts. A policy on a container governs every account beneath it. |
| `POLICY` | `POLICY_CREATE`, `POLICY_ARCHIVE` | Policies being archived, or for `POLICY_CREATE`, top-level accounts |
| `KEY` | `KEY_REGISTER`, `KEY_ARCHIVE` | Keys being archived, or for `KEY_REGISTER`, top-level accounts |
| `APPROVAL_GROUP` | `KEY_GROUP_CREATE`, `KEY_GROUP_ARCHIVE` | Groups being archived, or for `KEY_GROUP_CREATE`, top-level accounts |

A creation action type governs something that doesn't exist yet, so there's no ID to point the policy at. For `POLICY_CREATE`, `KEY_REGISTER`, and `KEY_GROUP_CREATE`, `resourceIds` lists the top-level accounts the policy governs. That's also how you write a firm-wide policy: target the top-level account. A create and its archive name different kinds of ID, so they go in separate policies.

### Conditions

Only the transaction action types (`WITHDRAWAL` and `DEPOSIT`) can carry conditions. A condition tree is made of nodes. A node either combines other nodes (`allOf`, `anyOf`, or a single-child `not`) or carries one or more of these checks:

| Leaf | Meaning |
| :- | :- |
| `assetType` | The asset the leaf matches, such as `BTC` or `USD`. Omit to match every asset. |
| `amount` | A floor on the notional value of the change itself: exactly one of `minInclusive` or `minExclusive`, as a decimal string. There's no upper bound; to cap, write a `deny` policy with the cap as its floor. |
| `cumulativeAmount` | A floor on the notional value of all matching changes over a rolling window: `value` (decimal string) and `period` (ISO 8601 duration, such as `P1D` or `PT12H`) |

When one node carries more than one check, all of them must match. A `not` may not contain `amount` or `cumulativeAmount` at any depth, because negating a floor would make a larger change need less than a smaller one. Any node can carry a `description` label.

```json USD withdrawals of $500,000 or more theme={null}
"conditions": { "assetType": "USD", "amount": { "minInclusive": "500000" } }
```

```json Any asset except BTC theme={null}
"conditions": { "not": { "assetType": "BTC" } }
```

```json A large wire on an account that already moved $10M in two days theme={null}
"conditions": {
  "assetType": "USD",
  "amount": { "minInclusive": "500000" },
  "cumulativeAmount": { "value": "10000000", "period": "P2D" }
}
```

### Required actions

A `requiredActions` tree is built from `allOf` and `anyOf` nodes and three kinds of requirement. There's no `not` here, and a node carrying one is rejected.

| Requirement | Meaning |
| :- | :- |
| `approvals` | An approvals tree. Each entry names an `approvalGroupId` and a `count` of distinct endorsements from that group. Combine entries with `allOf` and `anyOf`. |
| `deny` | Refuse the change outright. The submitting endpoint returns `403` and no action opens. Only `true` is accepted. A deny can't be overridden by another policy's `allow`; narrow its `conditions` instead. |
| `allow` | Let the change through with nothing further required. Only `true`, and only as the entire tree: `{ "allow": true }`. |

The top-level `requiredActions` object may also carry `settings.expiresIn`, an ISO 8601 duration for how long an opened action stays open before it expires. The default is `P14D`. When several policies govern one change, the shortest window wins.

> [!WARNING]
>
> The engine denies by default. Until your organization has an `allow` policy for an account and action type, every such change is refused. The one exception is policy governance itself: creating or archiving a policy that no policy governs is allowed, so you can write your first policies.

***

## Integration steps

### Step 1: Register approval keys

**`POST /v4/approvers/keys`** registers an existing Anchorage Digital API key as an approver. Registration isn't governed: the key is `ACTIVE` at once, but it approves nothing until it belongs to an approval group.

| Field | Required | Description |
| :- | :- | :- |
| `class` | Yes | `api_key`. Only Anchorage Digital API keys are supported. |
| `apiKeyId` | Yes | The key's ID: the hex-encoded SHA-256 of its access key, as shown when the key was issued |
| `publicKey` | Yes | The key's Ed25519 public key, hex-encoded (32 bytes) |
| `label` | Yes | A name for audit records, 1 to 128 characters. It doesn't identify the holder. |
| `approvalGroupId` | No | The group the key joins. A key belongs to one group for its whole life and can't be moved. Optional until approval groups can be created through this API. |

```bash Request theme={null}
curl --request POST \
     --url https://api.anchorage-staging.com/v4/approvers/keys \
     --header 'Api-Access-Key: {API Key}' \
     --header 'accept: application/json' \
     --header 'Api-Signature: {signature}' \
     --header 'Api-Timestamp: {unix epoch seconds}' \
     --header 'Idempotency-Key: 9c858901-8a57-4791-81fe-4c455b099bc9' \
     --header 'content-type: application/json' \
     --data '{
  "class": "api_key",
  "apiKeyId": "3f9a7c1e5b2d8e4f6a0c9b7d5e3f1a2c4b6d8e0f9a1c3e5b7d9f1a3c5e7b9d1f",
  "publicKey": "d75a980182b10ab7d54bfed3c964073a0ee172f3daa62325af021a68f707511a",
  "label": "treasury-ops-1"
}'
```

```json Response (202) theme={null}
{
  "data": {
    "id": "9c858901-8a57-4791-81fe-4c455b099bc9",
    "status": "ACTIVE",
    "createdAt": "2026-11-05T15:10:00Z"
  }
}
```

A key is nominated at most once per organization. **`GET /v4/approvers/keys`** lists keys in one status (`ACTIVE` by default, `ARCHIVED` to audit), **`GET /v4/approvers/keys/{keyId}`** returns one, and **`DELETE /v4/approvers/keys/{keyId}`** archives one. Archiving takes effect at once, isn't governed, and is final. Archiving an already archived key answers `202` again.

### Step 2: Create approval groups

**Under construction.** `POST`, `GET`, and `DELETE /v4/approvers/approval-groups` are in the reference but return mocked data only. The contract: a group has a `name`, its `approvalGroupId` is reserved and returned on creation even while `status` is `PENDING_APPROVAL`, and `GET /v4/approvers/approval-groups/{approvalGroupId}` returns its `members`, the keys registered into it. A key names its group at registration. This section will be updated when groups are available for testing.

### Step 3: Create a policy

**`POST /v4/policies`**

The response is `202` with the policy's reserved `id` and its `status`: `ACTIVE` if it took effect, or `PENDING_APPROVAL` with an `action` if a governing policy needs endorsements first.

The example below requires two endorsements from an approval group. You can create it today, but it can't be satisfied until approval groups and endorsements ship, so a change it governs is refused. Use the `allow` and `deny` shapes under [Common policies](#common-policies) for anything you want to take effect now.

```bash Request theme={null}
curl --request POST \
     --url https://api.anchorage-staging.com/v4/policies \
     --header 'Api-Access-Key: {API Key}' \
     --header 'accept: application/json' \
     --header 'Api-Signature: {signature}' \
     --header 'Api-Timestamp: {unix epoch seconds}' \
     --header 'Idempotency-Key: 3fa85f64-5717-4562-b3fc-2c963f66afa6' \
     --header 'content-type: application/json' \
     --data '{
  "name": "Standard withdrawal control",
  "description": "Any USD withdrawal of $10,000 or more needs two treasury approvals.",
  "target": {
    "resourceType": "ACCOUNT",
    "resourceIds": ["b6f3c1d4-8e2a-4f6b-9c3d-7a1e5f8b2c4d"],
    "actionTypes": ["WITHDRAWAL"]
  },
  "conditions": {
    "assetType": "USD",
    "amount": { "minInclusive": "10000" }
  },
  "requiredActions": {
    "approvals": { "approvalGroupId": "6ba7b813-9dad-11d1-80b4-00c04fd430cb", "count": 2 },
    "settings": { "expiresIn": "P3D" }
  }
}'
```

```json Response (202) theme={null}
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "ACTIVE",
    "createdAt": "2026-11-05T18:02:11Z"
  }
}
```

#### Common policies

**The first policy an organization writes.** Allow withdrawals and deposits everywhere beneath a top-level account. Without it, every transaction is refused.

```json theme={null}
{
  "name": "Baseline transactions",
  "target": {
    "resourceType": "ACCOUNT",
    "resourceIds": ["a2d9e6b7-4c1f-4a8e-9d2b-6f3a8c5e1b90"],
    "actionTypes": ["WITHDRAWAL", "DEPOSIT"]
  },
  "requiredActions": { "allow": true }
}
```

**A hard cap.** Refuse every BTC withdrawal from one account, whatever other policies allow.

```json theme={null}
{
  "name": "Block BTC withdrawals",
  "target": {
    "resourceType": "ACCOUNT",
    "resourceIds": ["b6f3c1d4-8e2a-4f6b-9c3d-7a1e5f8b2c4d"],
    "actionTypes": ["WITHDRAWAL"]
  },
  "conditions": { "assetType": "BTC" },
  "requiredActions": { "deny": true }
}
```

**Tiered approval with an override.** Two treasury approvals and one from compliance, or one executive approval, whichever comes first.

```json theme={null}
"requiredActions": {
  "approvals": {
    "anyOf": [
      {
        "description": "Standard flow",
        "allOf": [
          { "approvalGroupId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "count": 2 },
          { "approvalGroupId": "6ba7b811-9dad-11d1-80b4-00c04fd430c9", "count": 1 }
        ]
      },
      {
        "description": "Executive override",
        "approvalGroupId": "6ba7b812-9dad-11d1-80b4-00c04fd430ca",
        "count": 1
      }
    ]
  }
}
```

**Govern policy changes themselves.** Require compliance approval before any new policy is written beneath a top-level account.

```json theme={null}
{
  "name": "Policy creation control",
  "target": {
    "resourceType": "POLICY",
    "resourceIds": ["a2d9e6b7-4c1f-4a8e-9d2b-6f3a8c5e1b90"],
    "actionTypes": ["POLICY_CREATE"]
  },
  "requiredActions": {
    "approvals": { "approvalGroupId": "6ba7b811-9dad-11d1-80b4-00c04fd430c9", "count": 1 }
  }
}
```

Every ID in `resourceIds` must belong to your organization.

### Step 4: Read policies

**`GET /v4/policies`** resolves the policies that apply to one resource. Both `resourceType` and `resourceId` are required. For `ACCOUNT`, every policy naming the account or any account above it is returned, and `chain` lists the account IDs that were matched, nearest first. For the other families, pass the resource's own ID, or for a creation action type, a top-level account ID.

| Parameter | Description |
| :- | :- |
| `resourceType`, `resourceId` | Required. The resource to resolve for. |
| `actionType` | Only policies governing this action type |
| `status` | `ACTIVE` by default. `ARCHIVED` to audit retired policies. |
| `limit`, `after` | Pagination |

```bash Request theme={null}
curl --request GET \
     --url 'https://api.anchorage-staging.com/v4/policies?resourceType=ACCOUNT&resourceId=b6f3c1d4-8e2a-4f6b-9c3d-7a1e5f8b2c4d&actionType=WITHDRAWAL' \
     --header 'Api-Access-Key: {API Key}' \
     --header 'accept: application/json'
```

```json Response (200) theme={null}
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Standard withdrawal control",
      "status": "ACTIVE",
      "target": {
        "resourceType": "ACCOUNT",
        "resourceIds": ["b6f3c1d4-8e2a-4f6b-9c3d-7a1e5f8b2c4d"],
        "actionTypes": ["WITHDRAWAL"]
      },
      "conditions": { "assetType": "USD", "amount": { "minInclusive": "10000" } },
      "requiredActions": {
        "approvals": { "approvalGroupId": "6ba7b813-9dad-11d1-80b4-00c04fd430cb", "count": 2 },
        "settings": { "expiresIn": "P3D" }
      },
      "createdAt": "2026-11-05T18:02:11Z"
    }
  ],
  "page": { "endCursor": null },
  "chain": [
    "b6f3c1d4-8e2a-4f6b-9c3d-7a1e5f8b2c4d",
    "a2d9e6b7-4c1f-4a8e-9d2b-6f3a8c5e1b90"
  ]
}
```

**`GET /v4/policies/{policyId}`** returns one policy by ID. **`DELETE /v4/policies/{policyId}`** archives it. The definition is kept, `status` becomes `ARCHIVED`, and the change itself is governed by any `POLICY_ARCHIVE` policy that applies.

### Step 5: Endorse or reject actions

**Under construction.** The endorsement endpoints are in the reference but return mocked data only, and the engine doesn't yet open actions. The contract, so you can design for it:

* An **action** is the record of a change waiting for the endorsements its policy requires. It opens automatically and comes back as `action` on the change's `202`.
* `GET /v4/endorsements/actions` lists actions. `resourceType` is required, since IDs of every kind look the same. Filter with `resourceId`, `actionType`, and `status` (`PENDING`, `ENDORSED`, `REJECTED`, `EXPIRED`). There's no push notification, so poll.
* `POST /v4/endorsements/actions/{actionId}/endorse` and `/reject` take `keyId`, `payloadHash`, and `signature`: the approver's key signs the action's canonical payload. Each endorsement counts toward the leaf whose group the key belongs to. One rejection resolves the whole action. Endorsing or rejecting a resolved action is a no-op that returns the action as it stands, which makes the call safe to retry.
* An action's `expiresAt` is `submittedAt` plus the governing policy's `settings.expiresIn`. The requirement is fixed when the action opens. A policy changed afterward doesn't affect it.

This section will be updated when endorsements are available for testing.


## Related topics

- [Customizing admin policy](https://docs.anchorage.com/knowledge-base/porto/policies/customizing-admin-policy.md)
- [Customizing vault policies](https://docs.anchorage.com/knowledge-base/porto/policies/customizing-vault-policies.md)
- [Admin policies](https://docs.anchorage.com/knowledge-base/porto/policies/admin-policies.md)
- [Vault policies](https://docs.anchorage.com/knowledge-base/platform/users/vault-policies.md)
- [Administrator policy](https://docs.anchorage.com/knowledge-base/platform/users/administrator-policy.md)
