# 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](https://docs.sodot.dev/vertex-api-reference/#tag/admin/POST/admin/policies/set-user-default-policy) 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](https://docs.sodot.dev/vertex-api-reference/#tag/admin/POST/admin/policies/attach-policy-to-key) 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](/vertex/users_and_access_control) and [Rule Server](/mpc-infra/policies/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`](https://docs.sodot.dev/vertex-api-reference/#tag/admin/POST/admin/policies/add-external-rule) endpoint, add a new rule to the Vertex:

```bash
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`](https://docs.sodot.dev/vertex-api-reference/#tag/admin/GET/admin/policies/list-all-rules) endpoint.

### Create a Policy

Using the [`create-policy`](https://docs.sodot.dev/vertex-api-reference/#tag/admin/POST/admin/policies/create-policy) endpoint, create a new policy:

```bash
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`](https://docs.sodot.dev/vertex-api-reference/#tag/admin/GET/admin/policies/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`](https://docs.sodot.dev/vertex-api-reference/#tag/admin/POST/admin/policies/set-user-default-policy) can be used to attach a policy to a user:

```bash
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](/vertex/keygen/generating_keys) for more information.

The [`attach-policy-to-key`](https://docs.sodot.dev/vertex-api-reference/#tag/admin/POST/admin/policies/attach-policy-to-key) endpoint can be used to attach a policy to a key share:

```bash
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"
}'
```