Manage policies

Use this page for post-genesis policy operations. For policy mechanics, see Policies. For launch design, see Design your policies.

Policy changes use the standard intent flow. For signing, approval, and status checks, see Manage intents and approvals, Sign intents, and Check updates.

1. Go to Policies.
2. Click Create a policy.
3. Enter the policy details.
4. Click Submit for approval.
5. Sign the operation with the mobile app.

The policy is created after the intent is approved and executed.

Use these UI pages to enter policy details:

Custom conditions are JSON objects with type and expression fields. The expression is JavaScript. When the expression evaluates to true, the policy is eligible to apply to the intent. For condition and workflow syntax, see Policy reference.

Create a policy by submitting a v0_CreatePolicy intent. The following dry-run request body matches the Perform a dry run operation and can be signed and submitted with the Propose an intent operation after review.

Before you create a policy, prepare a new policy ID and a new intent ID in standard UUID format. Also confirm the role names, intent types, scope, condition paths, workflow, and rank.

{
  "author": {
    "id": "6ac20654-450e-29e4-65e2-1bdecb7db7c4",
    "domainId": "9067d363-6411-498b-a32b-15d230a86706"
  },
  "expiryAt": "2026-06-30T15:30:00.000Z",
  "targetDomainId": "9067d363-6411-498b-a32b-15d230a86706",
  "id": "7d256a32-812e-4a66-9a56-42ebfac5426a",
  "payload": {
    "id": "5b440ba5-d013-11eb-8cd0-dcfb48cfb3cb",
    "alias": "policy-governance",
    "rank": 700,
    "intentTypes": [
      "v0_CreatePolicy",
      "v0_UpdatePolicy",
      "v0_LockPolicy",
      "v0_UnlockPolicy"
    ],
    "scope": "Self",
    "scriptingEngine": "Javascript_v0",
    "condition": {
      "expression": "context.references.users[context.request.author.id].roles.includes('policy-operator')",
      "type": "Expression"
    },
    "workflow": [
      {
        "left": {
          "role": "policy-operator",
          "quorum": 2,
          "type": "RoleQuorum"
        },
        "right": {
          "role": "compliance",
          "quorum": 1,
          "type": "RoleQuorum"
        },
        "type": "And"
      }
    ],
    "lock": "Unlocked",
    "description": "Controls policy lifecycle operations in the root domain.",
    "customProperties": {},
    "type": "v0_CreatePolicy"
  },
  "description": "Create policy governance policy",
  "customProperties": {},
  "type": "Propose"
}

Dry run before submitting:

curl -X POST "${CUSTODY_API_URL}/v1/intents/dry-run" \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d @create-policy-intent.json

Submit the signed intent:

curl -X POST "${CUSTODY_API_URL}/v1/intents" \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "requestId: 8b6571b9-493c-49fb-9d92-e19b6f39f7cf" \
  -d @signed-create-policy-intent.json

Use v0_UpdatePolicy to replace the mutable policy fields. Include the current policy reference.id and reference.revision, then provide the updated alias, rank, scope, scripting engine, condition, workflow, description, and custom properties.

You can update only the approval workflow or update the full policy:

{
  "payload": {
    "reference": {
      "id": "5b440ba5-d013-11eb-8cd0-dcfb48cfb3cb",
      "revision": 3
    },
    "alias": "policy-governance",
    "rank": 750,
    "intentTypes": [
      "v0_CreatePolicy",
      "v0_UpdatePolicy",
      "v0_LockPolicy",
      "v0_UnlockPolicy"
    ],
    "scope": "Self",
    "scriptingEngine": "Javascript_v0",
    "condition": {
      "expression": "context.references.users[context.request.author.id].roles.includes('policy-operator')",
      "type": "Expression"
    },
    "workflow": [
      {
        "left": {
          "role": "policy-operator",
          "quorum": 2,
          "type": "RoleQuorum"
        },
        "right": {
          "role": "compliance",
          "quorum": 2,
          "type": "RoleQuorum"
        },
        "type": "And"
      }
    ],
    "description": "Controls policy lifecycle operations in the root domain.",
    "customProperties": {},
    "type": "v0_UpdatePolicy"
  }
}

Treat policy updates as high-risk operations. A policy update can change the policy that governs future policy updates.

System-signed intents are API-only proposals from service callers. They are submitted without a client-side payload signature and are matched only by policies whose intentOrigin is SystemSigned.

Use this pattern only for tightly scoped automation. At minimum:

• Set intentOrigin to SystemSigned.
• Specify the exact intentTypes the service caller can submit.
• Use a condition that checks the service submitter. For defense in depth, combine context.submitter.custodyRoles.includes(...) with a context.submitter.subject check for the expected service account.
• Omit workflow only when automatic execution is intentional. If you include a workflow, user-signed approvers must satisfy it.

The following example allows a service caller with the gas-station-service custody role and gas-station-svc subject to submit transaction order proposals. Replace both values with the role and subject issued by your identity provider.

{
  "author": {
    "id": "6ac20654-450e-29e4-65e2-1bdecb7db7c4",
    "domainId": "9067d363-6411-498b-a32b-15d230a86706"
  },
  "expiryAt": "2026-06-30T15:30:00.000Z",
  "targetDomainId": "9067d363-6411-498b-a32b-15d230a86706",
  "id": "7d256a32-812e-4a66-9a56-42ebfac5426a",
  "payload": {
    "id": "af1d2e33-9a94-4456-bcb3-895bba820d38",
    "alias": "gas-station-system-signed",
    "rank": 420,
    "intentTypes": ["v0_CreateTransactionOrder"],
    "intentOrigin": "SystemSigned",
    "scope": "SelfAndDescendants",
    "scriptingEngine": "Javascript_v0",
    "condition": {
      "expression": "context.submitter.type === 'Service' && context.submitter.custodyRoles.includes('gas-station-service') && context.submitter.subject === 'gas-station-svc'",
      "type": "Expression"
    },
    "lock": "Unlocked",
    "description": "Allows Gas Station service-submitted transaction orders.",
    "customProperties": {},
    "type": "v0_CreatePolicy"
  },
  "description": "Create system-signed Gas Station policy",
  "customProperties": {},
  "type": "Propose"
}

Submit this policy with the normal user-signed policy creation flow. The policy itself is a governance change and should be created, approved, and audited by users with authority to manage policies.

Lock a policy when it should stop matching new intents without being removed from the environment.

1. Go to Policies.
2. Open the contextual menu at the end of the policy row.
3. Select Lock policy or Unlock policy.
4. Click Submit for approval.
5. Sign the operation with the mobile app.

Submit v0_LockPolicy or v0_UnlockPolicy with the current policy reference:

{
  "payload": {
    "reference": {
      "id": "5b440ba5-d013-11eb-8cd0-dcfb48cfb3cb",
      "revision": 3
    },
    "type": "v0_LockPolicy"
  }
}

Use v0_UnlockPolicy with the same reference shape to re-enable the policy.

Policy changes can change the rules that govern future policy changes. Use a controlled sequence:

1. Confirm domain read access and required roles.
2. Confirm enough users exist for the intended quorum.
3. Deploy operational policies before policy-governance policies.
4. Deploy policy-governance policies after the users and fallback path exist.
5. Deploy emergency "break-glass" policies, high-privilege policies used only during incidents, only after their scope and intent types are explicit.
6. Dry run representative intents.

Before submitting a policy intent:

• Confirm the target domain and policy scope.
• Confirm the policy's intent types are deliberate.
• Confirm the condition is null-safe and uses the correct payload paths for each intent type.
• Confirm every workflow role exists in the target domain.
• Confirm quorum can be satisfied by independent users.
• For user-signed policies, confirm the first workflow step includes the maker role.
• For system-signed policies, confirm the workflow can be satisfied by user approvers, or that automatic execution is intentional.
• Confirm rank relative to other matching policies.
• Dry run representative intents before and after the policy change.

When a policy does not behave as expected:

1. Check intent type.
2. Check target domain and scope.
3. Check condition expression.
4. Check rank against other matching policies.
5. Check workflow roles and quorum.
6. Check lock state.

For field details, see Policy reference. For reusable models, see Policy examples.