Skip to main content
Version: 1.6

Setting Policies

A Policy is defined a set of Rules that are evaluated against the message or transaction that is being signed. All Rules of a Policy must be satisfied for the Policy to be satisfied. A Policy may be an empty set of Rules, in which case all transactions will always pass validation. Policies may be attached as a default Policy to a User, in which case all Key Shares generated by that User will be subject to the Policy. Alternatively, a Policy may be attached to a specific Key Share directly by a SystemAdmin.

Prerequisites​

Before setting up a Policy, we need to have a User and a Rule Server set up. Please refer to the Create User and Rule Server guides. We should now have the following information:

  • A SystemAdmin API Key
  • User Id
  • Rule Server URL
  • Rule Server public key
    • Public key JWT algorithm - ES256 or RS256

Creating a New Policy​

Create a Rule​

Using add-external-rule endpoint, we can add a new Rule to the Vertex:

curl -L -X POST 'https://<YOUR_VERTEX>/admin/policies/add-external-rule' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: <SYSTEMADMIN_API_KEY>' \
--data-raw '{
  "jwt_alg": "ES256-or-RS256",
  "name": "human-readable-name-for-rule",
  "pubkey": "PEM-encoded-public-key",
  "url": "URL-endpoint-for-rule-server"
}'

A rule_id will be returned in the response, which we will use to create a Policy.

List Rules​

It's possible to list all Rules using the list-all-rules endpoint.

Create Policy​

Using the create-policy endpoint, we can create a new Policy:

curl -L -X POST 'https://<YOUR_VERTEX>/admin/policies/create-policy' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: <SYSTEMADMIN_API_KEY>' \
--data-raw '{
  "name": "human-readable-name-for-policy",
  "rules": [
    "rule_id",
  ]
}'

A policy_id will be returned in the response, which we will use to attach the Policy to a Key Share.

List Policies​

It's possible to list all Policies using the list-all-policies endpoint.

Attaching a Policy to a Key Share​

There are 2 ways to attach a Policy to a Key Share:

Attach Policy as Default to User​

Attacing a Policy as default to a User will make all Key Shares generated by that User subject to the Policy. Using the set-user-default-policy endpoint, we can attach a Policy to a User:

curl -L -X POST 'https://<YOUR_VERTEX>/admin/policies/set-user-default-policy' \
-H 'Content-Type: application/json' \
-H 'Authorization: <SYSTEMADMIN_API_KEY>' \
--data-raw '{
  "policy_id": "string",
  "user_id": "string"
}'

Attach Policy to Key Share​

Attaching a Policy to a specific Key Share directly will make only that Key Share subject to the Policy. A key_id is required to attach a Policy to a Key Share, see Generating Keys for more information.

Using the attach-policy-to-key endpoint, we can attach a Policy to a Key Share:

curl -L -X POST 'https://<YOUR_VERTEX>/admin/policies/attach-policy-to-key' \
-H 'Content-Type: application/json' \
-H 'Authorization: <SYSTEMADMIN_API_KEY>' \
--data-raw '{
  "key_id": "string",
  "policy_id": "string"
}'