Skip to main content

Setting Policies

A policy is a set of rules that are enforced on each message/transaction/order that is being signed.
All policy rules 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. This can be used to enforce organization-wide policies on all keys imported by the relevant UI users. 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. The following information is required:

  1. A SystemAdmin API Key
  2. User Id
  3. Rule Server URL
  4. Rule Server public key
    1. Public key JWT algorithm - ES256 or RS256

Creating a New Policy​

Create a Rule​

Using the add-external-rule endpoint, 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 is returned in the response and is subsequently used to create a Policy.

List Rules​

It is possible to list all rules using the list-all-rules endpoint.

Create a Policy​

Using the create-policy endpoint, 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 is returned in the response and is subsequently used to attach the policy to a key share.

List Policies​

It is possible to list all policies using the list-all-policies endpoint or view these via the UI.

Attaching a Policy to a Key Share​

There are two ways to attach a policy to a key share:

Attach Policy as Default for a User​

Attaching a policy as default for a user will enforce that policy by default on all key shares generated by that user. The set-user-default-policy can be used to 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 a Specific Key Share​

Attaching a policy to a specific key share explicitly will enforce the policy on that key share.
A key_id is required to attach a policy to a key share, see Generating Keys for more information.

The attach-policy-to-key endpoint can be used to 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"
}'