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

# Define a policy

> Create a policy and submit it for approval. Active immediately unless a governing policy still
needs endorsements, in which case `status` is `PENDING_APPROVAL` and `action` is present.



## OpenAPI

````yaml /knowledge-base/openapi/v4.yaml post /policies
openapi: 3.1.0
info:
  title: Anchorage Digital Account APIs (v4)
  version: 4.0.0-beta
  description: >-
    Reference for the Anchorage Digital v4 API, the surface behind Crypto as a
    Service: account management (accounts and the account tree, beneficiaries,
    freeze/unfreeze/close), balances and transactions, trusted destinations,
    orders and allocations, withdrawals, deposit instructions, deposit
    attributions, the policy engine (policies, approval keys), and supported
    asset types. Approval groups, endorsements, compliance profiles, customers
    (onboarding), fee configuration updates, interest enrollment, funding
    allocations, and destination removal are under construction and return
    mocked data only.


    Status: BETA. The v4 API is available in the sandbox only
    (https://api.anchorage-staging.com/v4) and is not available in production
    yet. The contract may change until general availability. Which endpoints are
    live, in final testing, or under construction:
    https://docs.anchorage.com/platform/developers/caas/caas-overview


    Authentication: every request carries an `Api-Access-Key` header. Every
    POST, PATCH, and DELETE additionally requires an `Idempotency-Key`, and is
    signed with `Api-Signature` (hex-encoded Ed25519 over
    `timestamp_epoch_seconds + uppercase(http_method) + request_path +
    request_body`) plus `Api-Timestamp` (unix epoch seconds).


    Pagination: list endpoints accept `after` (cursor) and `limit` (page size, 1
    to 1000, default 100) and return a `page.endCursor` to continue from. Errors
    use a common envelope with a human-readable `message`; batch endpoints
    return a result per item instead.


    Guides: https://docs.anchorage.com/platform/developers/caas/caas-overview
servers:
  - url: https://api.anchorage-staging.com/v4
security:
  - Api-Access-Key: []
tags:
  - name: Accounts
  - name: Compliance Profiles
  - name: Balances
  - name: Transactions
  - name: Trusted Destinations
  - name: Orders & Allocations
  - name: Withdrawals
  - name: Deposit Instructions
  - name: Deposit Attributions
  - name: Policies
  - name: Approval Groups
  - name: Endorsements
  - name: Customers
  - name: Asset Types
paths:
  /policies:
    post:
      tags:
        - Policies
      summary: Define a policy
      description: >-
        Create a policy and submit it for approval. Active immediately unless a
        governing policy still

        needs endorsements, in which case `status` is `PENDING_APPROVAL` and
        `action` is present.
      operationId: createPolicy
      parameters:
        - name: Idempotency-Key
          in: header
          schema:
            type: string
          required: true
          description: >-
            Client-supplied key that deduplicates retried requests. Reusing a
            key returns the original result instead of repeating the action.
        - name: Api-Signature
          in: header
          required: true
          schema:
            type: string
            pattern: ^[0-9A-Fa-f]{128,160}$
          description: >-
            A hex-encoded Ed25519 signature of `timestamp_epoch_seconds +
            uppercase(http_method) + request_path + request_body`.
        - name: Api-Timestamp
          in: header
          required: true
          schema:
            type: integer
            format: int64
          description: Current timestamp, represented as unix epoch seconds
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PolicyCreateRequest'
      responses:
        '202':
          description: Change accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyChangeAcceptedResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetails'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetails'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetails'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetails'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetails'
components:
  schemas:
    PolicyCreateRequest:
      title: Policy Create Request
      type: object
      required:
        - name
        - target
        - requiredActions
      properties:
        name:
          type: string
          description: Human-readable policy name.
        description:
          type: string
          description: Optional human-readable explanation of what this policy is for.
        target:
          $ref: '#/components/schemas/PolicyTarget'
        conditions:
          allOf:
            - $ref: '#/components/schemas/ConditionNode'
          description: >-
            When present, this policy only applies to changes matching this
            boolean tree. Omit for a policy

            that applies to every change matching target.


            Only the transaction action types (`WITHDRAWAL`, `DEPOSIT`) may
            carry one. Every condition is

            about a change's asset and value, and the other action types have
            neither, so a condition on

            one of them could never match.
        requiredActions:
          allOf:
            - $ref: '#/components/schemas/RequiredActionNode'
            - type: object
              properties:
                settings:
                  $ref: '#/components/schemas/RequiredActionSettings'
          description: >-
            What a matching change must satisfy — approvals, deny or allow
            today, with room for other

            requirement types alongside them later — as a boolean tree, plus
            optional settings governing

            the action opened when the tree isn't already satisfied. settings
            belongs on this root object

            only, not on nodes inside the tree.


            A tree that resolves to deny refuses the change with 403 and opens
            no action, so settings has

            nothing to govern in that case. A tree of exactly {"allow": true}
            lets the change through with

            nothing further required, so settings has nothing to govern there
            either.
    PolicyChangeAcceptedResponse:
      title: Policy Change Accepted Response
      type: object
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/PolicyChangeAccepted'
    ErrorDetails:
      title: ErrorDetails
      type: object
      properties:
        message:
          description: A human-readable message providing more details about the error.
          example: Missing required field 'amount'.
          type: string
      required:
        - message
    PolicyTarget:
      title: Policy Target
      type: object
      required:
        - resourceType
        - resourceIds
        - actionTypes
      description: Which resources and action types this policy governs.
      properties:
        resourceType:
          allOf:
            - $ref: '#/components/schemas/ResourceType'
          description: >-
            The family of action types this policy governs, and the namespace
            resourceIds refer to (root account ids for a creation action type).
        resourceIds:
          type: array
          items:
            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
            description: A UUID in canonical lowercase hyphenated form.
            type: string
            format: uuid
            example: 3486b413-93d3-4447-afce-2b9c9dc34a32
          minItems: 1
          description: >-
            The resources this policy applies to, in canonical lowercase
            hyphenated UUID form. A single policy

            can target more than one resource at once. For the creation action
            types `POLICY_CREATE`,

            `KEY_REGISTER`, and `KEY_GROUP_CREATE`, which have no pre-existing
            resource to scope against, list

            the root account ids the policy governs: a policy on a root account
            governs creations anywhere

            beneath it. At least one id is always required.
        actionTypes:
          type: array
          items:
            $ref: '#/components/schemas/ActionType'
          minItems: 1
          description: The action types this policy governs.
    ConditionNode:
      title: Condition Node
      type: object
      minProperties: 1
      description: >-
        A node in the conditions boolean tree. A composition node carries
        exactly one of allOf, anyOf or not —

        allOf/anyOf are arrays of child ConditionNodes, not is a single child
        ConditionNode that must NOT be

        satisfied. A leaf node instead carries one or more of assetType / amount
        / cumulativeAmount, which

        are ANDed together when more than one is present on the same node. Any
        kind of node may carry

        description, a human-readable label for that branch.


        An empty node is rejected. Omit conditions entirely for a policy that
        applies to every change matching

        target.
      properties:
        description:
          type: string
          description: Optional label for this branch.
        allOf:
          type: array
          items:
            $ref: '#/components/schemas/ConditionNode'
          minItems: 1
          description: Every child node must be satisfied.
        anyOf:
          type: array
          items:
            $ref: '#/components/schemas/ConditionNode'
          minItems: 1
          description: At least one child node must be satisfied.
        not:
          allOf:
            - $ref: '#/components/schemas/ConditionNode'
          description: >-
            The child node must NOT be satisfied. It may not contain an amount
            or cumulativeAmount at any depth.
        assetType:
          allOf:
            - $ref: '#/components/schemas/PolicyAssetType'
          description: >-
            The asset this leaf matches. An amount or cumulativeAmount on the
            same node counts only changes in this asset. Omit to apply to every
            asset.
        amount:
          $ref: '#/components/schemas/AmountCondition'
        cumulativeAmount:
          $ref: '#/components/schemas/CumulativeAmountCondition'
    RequiredActionNode:
      title: Required Action Node
      type: object
      minProperties: 1
      description: >-
        A node in the requiredActions boolean tree. A composition node carries
        allOf and/or anyOf. A leaf

        node instead carries approvals — an ApprovalNode boolean tree — or deny,
        or allow. The shape leaves

        room for future requirement types alongside them.


        The engine denies by default: a change that no active policy governs is
        refused. A change goes

        through only when a policy governing it says so — an allow leaf, or an
        approvals tree the received

        endorsements satisfy — and no governing policy denies it. The exceptions
        are the policy routes

        themselves: creating or archiving a policy that no policy governs is
        allowed, so an organization

        can write its first policies.


        There is no not at this level, and a node carrying one is rejected:
        negating a requirement inverts

        what a change must satisfy, which is never what a policy author means.
        The approvals tree below has

        no not either — see ApprovalNode. The schema itself stays open so future
        requirement types can be

        added without breaking clients that validate responses, so the rejection
        is enforced on submission

        rather than by shape.


        An empty node is rejected. To refuse a change outright, say so with
        deny; to let it through, say so

        with allow; never by omission.
      properties:
        description:
          type: string
          description: Optional label for this branch.
        allOf:
          type: array
          items:
            $ref: '#/components/schemas/RequiredActionNode'
          minItems: 1
          description: Every child node must be satisfied.
        anyOf:
          type: array
          items:
            $ref: '#/components/schemas/RequiredActionNode'
          minItems: 1
          description: At least one child node must be satisfied.
        approvals:
          $ref: '#/components/schemas/ApprovalNode'
        deny:
          type: boolean
          description: >-
            Leaf only — a requirement that no endorsement can ever meet. A
            change matching this policy's

            target and conditions is refused outright: the submitting endpoint
            returns 403 and no action is

            opened, so there is nothing to endorse and nothing to wait out.
            Scope the refusal with

            conditions — a policy whose conditions match only BTC and whose
            requiredActions is

            {"deny": true} blocks BTC and leaves every other asset alone.


            Only true is accepted. {"deny": false} is rejected on submission: it
            reads as "do not deny" but

            states no requirement at all. To let a change through, write
            {"allow": true}.


            A deny cannot be bought off elsewhere. Every policy governing a
            change must be satisfied, so

            one denying policy refuses it no matter what another policy's allow
            or approvals would have

            permitted. To carve out an exception, narrow the denying policy's
            conditions rather than adding

            a second policy to override it.
        allow:
          type: boolean
          description: >-
            Leaf only, and the whole tree: a requiredActions of exactly
            {"allow": true}. The engine denies

            by default, and this is how a policy lets the changes matching its
            target and conditions

            through with nothing further required. A typical first policy
            targets the root account with

            the action types an organization uses; narrower deny policies then
            carve out what must not

            happen, and a deny always wins over an allow governing the same
            change.


            Only true is accepted, and only at the root: under allOf the leaf
            would be a no-op sibling,

            under anyOf it would make every sibling requirement optional. A
            policy that means to allow

            says only that.
    RequiredActionSettings:
      title: Required Action Settings
      type: object
      description: >-
        Settings for the action this policy opens when its requiredActions tree
        isn't already satisfied.

        Applies to the action as a whole, so it lives on the root
        requiredActions object rather than on any

        node inside the tree.
      properties:
        expiresIn:
          type: string
          format: duration
          default: P14D
          description: >-
            How long an action opened by this policy stays open before it is
            marked EXPIRED, as an ISO 8601

            duration. Measured from the action's submittedAt. Omit for the
            default of 14 days (P14D). When more

            than one policy governs the same change, the shortest expiresIn
            among them applies.
    PolicyChangeAccepted:
      title: Policy Change Accepted
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 3486b413-93d3-4447-afce-2b9c9dc34a32
        status:
          $ref: '#/components/schemas/PolicyStatus'
        action:
          $ref: '#/components/schemas/ActionRef'
        createdAt:
          type: string
          format: date-time
          example: '2019-01-02T12:34:56.000Z'
    ResourceType:
      title: Resource Type
      type: string
      enum:
        - ACCOUNT
        - POLICY
        - KEY
        - APPROVAL_GROUP
      description: >-
        Which namespace a resource id belongs to, and which family of action
        types that resource

        participates in:


        * `ACCOUNT` — transaction action types (`WITHDRAWAL`, `DEPOSIT`) and
        trusted-destination
          action types (`TRUSTED_DESTINATION_ADD`, `TRUSTED_DESTINATION_REMOVE`). A trusted destination
          is added to or removed from an account, so such a policy scopes to an account, to any account
          above it, or to the organization — never to an individual destination.
        * `POLICY` — policy-governance action types (`POLICY_CREATE`,
        `POLICY_ARCHIVE`).

        * `KEY` — approval-key-governance action types (`KEY_REGISTER`,
        `KEY_ARCHIVE`).

        * `APPROVAL_GROUP` — approval-group-governance action types
        (`KEY_GROUP_CREATE`,
          `KEY_GROUP_ARCHIVE`).

        For the creation action types (`POLICY_CREATE`, `KEY_REGISTER`,
        `KEY_GROUP_CREATE`) there is no

        resource yet, so a policy's `resourceIds` are the root account ids it
        governs even though its

        `resourceType` names the family being created.
    ActionType:
      title: Action Type
      type: string
      enum:
        - WITHDRAWAL
        - DEPOSIT
        - TRUSTED_DESTINATION_ADD
        - TRUSTED_DESTINATION_REMOVE
        - POLICY_CREATE
        - POLICY_ARCHIVE
        - KEY_REGISTER
        - KEY_ARCHIVE
        - KEY_GROUP_CREATE
        - KEY_GROUP_ARCHIVE
    PolicyAssetType:
      title: Policy Asset Type
      type: string
      example: BTC
      description: >-
        A string representing a type of asset, which usually corresponds to the
        asset's ticker symbol. Use `/asset-types` to list all of the supported
        asset types for your organization.
    AmountCondition:
      title: Amount Condition
      description: >-
        Checks a change's own notional value against a floor, written as exactly
        one of minInclusive or

        minExclusive. There is no upper bound: to cap a value, write a deny
        policy whose floor is the cap. The

        asset is the assetType on the same condition node.
      oneOf:
        - $ref: '#/components/schemas/InclusiveFloorAmountCondition'
        - $ref: '#/components/schemas/ExclusiveFloorAmountCondition'
      not:
        required:
          - minInclusive
          - minExclusive
    CumulativeAmountCondition:
      title: Cumulative Amount Condition
      type: object
      required:
        - value
        - period
      description: >-
        Checks notional value summed over a rolling window, not just this one
        change.
      properties:
        value:
          type: string
          pattern: ^\d+(\.\d+)?$
          description: >-
            The cumulative notional value threshold over the rolling window, as
            a positive decimal number encoded as a string.
        period:
          type: string
          format: duration
          description: >-
            The rolling window over which value is evaluated, as an ISO 8601
            duration.
    ApprovalNode:
      title: Approval Node
      type: object
      minProperties: 1
      description: >-
        A node in the approvals boolean tree. A leaf node carries
        approvalGroupId and count. A composition node

        instead carries allOf and/or anyOf. Any kind of node may carry
        description, a human-readable

        label for that branch.


        There is no not at any depth of this tree, and a node carrying one is
        rejected. "Must not be endorsed

        by this group" is satisfied by inaction and falsified by a signature: it
        would hold until the named

        group actually signs and then become permanently unsatisfiable, which
        inverts what collecting

        endorsements means.


        An empty node is rejected, as is a count of zero. An approval
        requirement that nothing can satisfy is

        not expressible here — use the deny leaf on RequiredActionNode to refuse
        a change on purpose.
      properties:
        description:
          type: string
          description: Optional label for this branch.
        approvalGroupId:
          description: Leaf only — the approval group required to endorse.
          type: string
          format: uuid
          example: 3486b413-93d3-4447-afce-2b9c9dc34a32
        count:
          type: integer
          minimum: 1
          description: >-
            Leaf only — number of endorsements required from approvalGroupId. At
            least 1.
        allOf:
          type: array
          items:
            $ref: '#/components/schemas/ApprovalNode'
          minItems: 1
          description: Composition only — every child node must be satisfied.
        anyOf:
          type: array
          items:
            $ref: '#/components/schemas/ApprovalNode'
          minItems: 1
          description: Composition only — at least one child node must be satisfied.
    PolicyStatus:
      title: Policy Status
      type: string
      enum:
        - PENDING_APPROVAL
        - ACTIVE
        - ARCHIVED
    ActionRef:
      title: Action Reference
      type: object
      required:
        - id
      description: >-
        A pointer to the action opened for this change. Present only when policy
        evaluation found every

        other requirement already satisfied except one: it still needs more
        endorsements. Absent means the

        change applied immediately with no policy blocking it.
      properties:
        id:
          description: The action's id in the Endorsements surface.
          type: string
          format: uuid
          example: 3486b413-93d3-4447-afce-2b9c9dc34a32
        reason:
          type: string
          description: Optional human-readable explanation of why endorsement is needed.
    InclusiveFloorAmountCondition:
      title: Inclusive Floor
      type: object
      required:
        - minInclusive
      properties:
        minInclusive:
          type: string
          pattern: ^\d+(\.\d+)?$
          description: >-
            Inclusive lower bound on the notional value, as a positive decimal
            number encoded as a string.
    ExclusiveFloorAmountCondition:
      title: Exclusive Floor
      type: object
      required:
        - minExclusive
      properties:
        minExclusive:
          type: string
          pattern: ^\d+(\.\d+)?$
          description: >-
            Exclusive lower bound on the notional value, as a positive decimal
            number encoded as a string.
  securitySchemes:
    Api-Access-Key:
      type: apiKey
      name: Api-Access-Key
      in: header
      description: An API key associated with a security role

````

## Related topics

- [Administrator policy](https://docs.anchorage.com/knowledge-base/platform/users/administrator-policy.md)
- [Vault policies](https://docs.anchorage.com/knowledge-base/platform/users/vault-policies.md)
- [Admin policies](https://docs.anchorage.com/knowledge-base/porto/policies/admin-policies.md)
- [Policies overview](https://docs.anchorage.com/knowledge-base/platform/users/policies.md)
- [Adding rules to policies](https://docs.anchorage.com/knowledge-base/porto/policies/adding-rules.md)
