ReferenceAPI ReferencePolicy

Create policy

POST/policies●Define rules that control access, approval requirements, or automated behaviors.

Policies are enforced unless their status is set to inactive. Use proofs to activate or deactivate a policy.

The schema field determines the policy type:

  • access — control who can perform actions on records
  • status — define available statuses and quorum requirements for transitions
  • labels — enforce label uniqueness and assignment rules
  • schedule — trigger actions on a time-based schedule
  • processing — invoke bridges for anchor operations
  • authentication — configure OAuth 2.0 token issuance

Rules within policies support filters using MongoDB-style query syntax for fine-grained matching.

Broadcasts the policy-created signal. Use effects to subscribe.

POST
/policies

Usage Examples

curl -X POST "http://localhost:3000/v2/policies" \  -H "x-ledger: <YOUR LEDGER HANDLE>" \  -H "Content-Type: application/json" \  -d '{    "hash": "7cf05252a4472a155a39edc222a26cb8fc9f85d60ecb2841e028b02c379de963",    "data": {      "handle": "admin-policy",      "schema": "access",      "record": "any",      "values": [        {          "action": "any",          "signer": {            "$circle": "admin"          }        }      ]    },    "meta": {      "proofs": [        {          "method": "ed25519-v2",          "digest": "374422ed861753b7ae317172751fae081a8450e515387c120ed8eace1733b612",          "public": "AN6XpZ7T8FDCkjbSpIVE2cioQ7hajp8DBTOioz/TSZ8=",          "result": "2UOiiMOYmQFsduziE62Kg8F0lZ4mwZYYF6lXijqjGDMWxaqCv72mF42P8/bVsJMGQattLAXFrencq5/Mc7rVCQ==",          "custom": {            "moment": "2025-04-05T14:30:00.000Z",            "status": "created"          }        }      ]    }  }'
{
  "luid": "$plc.-01xK6wXyZ7iX9BC8",
  "hash": "7cf05252a4472a155a39edc222a26cb8fc9f85d60ecb2841e028b02c379de963",
  "data": {
    "handle": "admin-policy",
    "schema": "access",
    "record": "any",
    "values": [
      {
        "action": "any",
        "signer": {
          "$circle": "admin"
        }
      }
    ]
  },
  "meta": {
    "status": "created",
    "moment": "2025-04-05T14:30:00.050Z",
    "owners": [
      "AN6XpZ7T8FDCkjbSpIVE2cioQ7hajp8DBTOioz/TSZ8="
    ],
    "proofs": [
      {
        "signer": "ach-admin",
        "method": "ed25519-v2",
        "digest": "374422ed861753b7ae317172751fae081a8450e515387c120ed8eace1733b612",
        "public": "AN6XpZ7T8FDCkjbSpIVE2cioQ7hajp8DBTOioz/TSZ8=",
        "result": "2UOiiMOYmQFsduziE62Kg8F0lZ4mwZYYF6lXijqjGDMWxaqCv72mF42P8/bVsJMGQattLAXFrencq5/Mc7rVCQ==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z",
          "status": "created"
        }
      },
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "582080899a94d868fc76331c26bf3bbe3de75fe1c140be5bb7cfe9ccb51fa629",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "SOn8asw27mPCGLkbaRkIcZhUWAv6uCAFRIqdWnBt+rNmVMqSLybMytGLTVGKGeglhfdPY/L7TQ3+KVvOenCtDQ==",
        "custom": {
          "luid": "$plc.-01xK6wXyZ7iX9BC8",
          "moment": "2025-04-05T14:30:00.050Z",
          "status": "created"
        }
      }
    ]
  }
}
{
  "hash": "b7eb7ccf5ffc126951e13e29a8dcfdaf95db859715d4edfc2d16f59a79d4cd58",
  "data": {
    "reason": "auth.unauthorized",
    "detail": "Invalid token."
  },
  "meta": {
    "proofs": [
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "3acece870c4118bfe4223118e4d2f3cfd5b8947a7093785b66d49aa57fa2890a",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "gnK63DqqWDY/UXvnZHixDKPKS6tfeGHgdARylnPiJLwQGyYxuD97TYbSg2wrzsf/bDrHwQYZaf8Gu5ryYP0UAA==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z"
        }
      }
    ]
  }
}
{
  "hash": "9ec02726b50650add8acfd124c6defeb978a9ac252a5de888f9493ddc701e927",
  "data": {
    "reason": "auth.forbidden",
    "detail": "Request is not authorized"
  },
  "meta": {
    "proofs": [
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "4f8cbdc38d73348de0c31805c783c84a0fecc6be736d7e187004ba68cd00e675",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "P3hRnveehtuobb4AIO56XBmiduvmYJbpdmOHltG/IifBEH7QSWdv/0pqled4SO9x1Ne3oXuWxJy40DzMvx1MBA==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z"
        }
      }
    ]
  }
}
{
  "hash": "d6c59a6df7165fa4a75159799ca5f5e26e544cbb8769eced3d35d8021f6f7935",
  "data": {
    "reason": "record.not-found",
    "detail": "Signer not found"
  },
  "meta": {
    "proofs": [
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "78cf86f34aefcf9da6ed4167a38aac0a2739f68f7bafb1d3e033c01ed1b6cdf1",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "9Ledk+/iAAtj+uLjGe2afq4kID7n8UQD6UpRpLBCujxFjxddq0uZ2tnYRTAXmYdHDkbF0uXqtNM9qO3xhEtpAA==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z"
        }
      }
    ]
  }
}
{
  "hash": "dc973d46dd35baa27b0ec5a107e2ee3a8cc57116d086dd868dd0f044a8de7d92",
  "data": {
    "reason": "record.duplicated",
    "detail": "Ledger with handle instant-payments already exists."
  },
  "meta": {
    "proofs": [
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "3e1317cc165d132f95ec2f6374890063c162d905d86b33270f97416f8441a872",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "b+0gSDCUzjEKlZQ/c40yqNpZoyQxCFsbV1Ut5/0zM2wM46xmHMBj3qeo3/GDaFD4NgSNm2G8n1f9c9rfvkl3BA==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z"
        }
      }
    ]
  }
}

{
  "hash": "1c084e8dcfb9bb84bc8ea96e9e137b149a34b2bbd85f8e60b4263f5aba980476",
  "data": {
    "custom": {
      "errors": [
        {
          "instancePath": "/handle",
          "schemaPath": "#/properties/handle/pattern",
          "keyword": "pattern",
          "params": {
            "pattern": "^[a-zA-Z0-9_\\-+.]+$"
          },
          "message": "must match pattern \"^[a-zA-Z0-9_\\-+.]+$\""
        }
      ]
    },
    "reason": "record.schema-invalid",
    "detail": "Schema validator error: data.handle must match pattern \"^[a-zA-Z0-9_\\-+.]+$\""
  },
  "meta": {
    "proofs": [
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "7a5febb431719b6f43d7e88e79211308e16ac651b71b339276373fdb4e7c3760",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "2/1zYw4AaIzsIHfOIC6V/CHw6owbjYHt48cwmFOig0ibeT0IbojLmj1RCRi8W00ka0udPa9WsacWDd7ObMY8CA==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z"
        }
      }
    ]
  }
}

{
  "hash": "93a5f4d97a42c2df97f827c58ff7768d02568c15aca931e22b81fa3160ba0df3",
  "data": {
    "reason": "api.unexpected-error",
    "detail": "An unexpected error occurred"
  },
  "meta": {
    "proofs": [
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "efaf5360143b586917d9636779ad6e08571c5b06909a20dd0f5eba4bf3be7eae",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "hERh6Aecj59iR+Fb25OQsHJScOi4t8EiffKSfjlMQdjHMccTnfDlgZFdaJzXzUtpSwy/NHq0l+7ydh3HSWCoAg==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z"
        }
      }
    ]
  }
}

Header Parameters

x-ledger?|

The unique identifier of ledger in context for multi tenant requests.

Request Body

application/json

Policy body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

Policy

Define rules that control how the ledger behaves.

List policies GET

Use this endpoint to review system configuration and business rules, find policies targeting a specific resource type, or audit which rules apply in a domain. Supported filters: - `data.record` — target resource type - `data.schema` — policy type - `meta.status` — record status - `meta.labels` — record labels - `meta.domain` — domain scope - `data.custom.<field>` — any custom field (may be slower on large datasets)