# Create an access policy

Canonical page: https://docs.ovok.com/access-policies/create-access-policy

Create a policy with the FHIR API, then attach it to the people who should hold it. The Slim policy route is a shorter path for simple roles, but it drops scoping fields. Read [the differences](#slim-policy-route) before you use it.

```bash
export OVOK_TOKEN='<access token of a project admin>'
```

## Create a policy [#create-a-policy]

Send an `AccessPolicy` to `/fhir/R4/AccessPolicy`. The rules are those of the [policy model](/access-policies/policy-model): a `resourceType`, the `interaction` list, and optionally `criteria` and `readonly`.

<Recording name="ovok-console-access-policies" alt="Creating an Observation access policy in the Console and setting it as the default for new practitioners" />

```bash
curl --request POST \
  --url 'https://api.sandbox.ovok.com/fhir/R4/AccessPolicy' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/fhir+json' \
  --data '{
    "resourceType": "AccessPolicy",
    "name": "Ward A nurse",
    "resource": [
      {
        "resourceType": "Patient",
        "criteria": "Patient?organization=Organization/{{WARD_ORGANIZATION_ID}}",
        "interaction": ["read", "search"]
      },
      { "resourceType": "Observation", "readonly": true },
      { "resourceType": "signals_alerts", "interaction": ["read", "update"] }
    ]
  }'
```

The answer is the stored policy with its `id`. Note the `id`: every route below takes it. Add `signals_*` rows only for [the Signals routes](/access-policies/signals) the role needs.

## Replace a policy [#replace-a-policy]

`PUT /fhir/R4/AccessPolicy/{{ACCESS_POLICY_ID}}` takes the whole policy, with the same `id` in the body.

## Attach the policy [#attach-the-policy]

Creating a policy gives it to nobody. Attach it in one of these ways.

| Who | How | Policy |
| --- | --- | --- |
| Every new practitioner | Set the [default practitioner policy](/settings-and-features/settings/default-practitioner-access-policy). Self-registration assigns it. | `AccessPolicy/<id>` of this project |
| A new practitioner by invitation | Send `accessPolicyId` to [`POST /v1/slim/invite/practitioner`](/slim-apis/invite/invite-practitioner). | A policy at or below your own rank |
| Every new patient | Set the project text setting `DEFAULT_PATIENT_ACCESS_POLICY`, as below. | `AccessPolicy/<id>` of this project |

Set the default patient policy with a project admin token:

```bash
curl --request PUT \
  --url 'https://api.sandbox.ovok.com/v1/project/settings/values/DEFAULT_PATIENT_ACCESS_POLICY' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"value":"AccessPolicy/{{ACCESS_POLICY_ID}}"}'
```

A value that is not `AccessPolicy/<id>` of a policy in this project answers `422` with code [`INVALID_SETTING_VALUE`](/errors/invalid-setting-value). Patient registration and patient invitations refuse until the project has a default patient policy. See [default policies](/access-policies/defaults).

## Slim policy route [#slim-policy-route]

`POST /v1/slim/policy` and `PUT /v1/slim/policy/:id` create or replace a policy and set who holds it in one request. See [Create access policy](/slim-apis/policy/create-access-policy) and [Update access policy](/slim-apis/policy/update-access-policy).

| | FHIR `/fhir/R4/AccessPolicy` | Slim `/v1/slim/policy` |
| --- | --- | --- |
| `criteria` on a rule | Kept | Ignored without an error |
| `readonly` on a rule | Kept | Ignored without an error |
| `policy.id` on create | Not applicable | Ignored |
| `members` | Not part of the policy | Required, may be empty |
| Who holds the policy | Attach it separately | Set by the request: listed members now hold it |
| Rank | Not used | Taken from `policy.name`: `System Owner`, `Admin`, or any other name. You cannot create or update a policy above your own rank. |
| Who may call | The FHIR store decides | `POST` needs `AccessPolicy:create` and `ProjectMembership:update`, `PUT` needs `Practitioner:create`; project admins skip the check |
| Added rules | None | Ovok adds `Consent` interactions, and more for some policies |
| Copy to child projects | Not copied | Copied by name into each direct child project |

<Callout type="warn">Do not copy a `criteria` rule from this page into a Slim request: Ovok drops it and the policy then grants access to every matching resource.</Callout>

Use the FHIR route for any policy that scopes with `criteria` or uses `readonly`. Use the Slim route for a plain role of resource types and interactions that you want to assign at the same time. A Slim `PUT` also removes `criteria` and `readonly` from a policy created through FHIR.

## Related [#related]

- [AccessPolicy model and membership](/access-policies/policy-model)
- [Default policies](/access-policies/defaults)
- [Signals route policies](/access-policies/signals)
- [Invite a project admin](/invitations/team-members)
