# Create access policy

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

| Method | Path |
| --- | --- |
| `POST` | `/v1/slim/policy` |

[Authentication](/authentication) · [Access policies](/access-policies)

Creates an access policy (role) in your project and assigns it to the listed practitioners. Use it to define a new role.

**Auth:** Bearer token for a practitioner, project admin or System Owner session. The caller's access policy must grant `AccessPolicy:create` and `ProjectMembership:update` (project admins skip this check).
**Scope:** The policy is created in the caller's project (from the token).

## Request [#request]

### Body [#body]

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `policy` | `object` | Yes | The policy to create. |
| `policy.name` | `string` | Yes | Policy name, 1 to 255 characters. The name also decides the rank of the policy (see Behaviour). |
| `policy.resourceType` | `"AccessPolicy"` | Yes | Must be `AccessPolicy`. |
| `policy.resource` | `object[]` | Yes | The resource rules. May be empty. |
| `policy.resource[].resourceType` | `string` | Yes | Resource type the rule covers, 1 to 255 characters, for example `Patient`. `*` covers every resource type. |
| `policy.resource[].interaction` | `string[]` | Yes | Allowed interactions, each one of `read`, `create`, `update`, `delete`, `search`, `history`, `vread`. May be empty. |
| `members` | `object[]` | Yes | Profiles that get the policy. May be empty. |
| `members[].reference` | `string` | Yes | Profile reference, for example `Practitioner/<id>`. |
| `members[].display` | `string` | Yes | Display name. Required, but not stored: the response takes names from the practitioner profile. |

Any other field is ignored. This includes rule fields such as `criteria` and `readonly`, and `policy.id`. This route cannot create rules that use them.

## Behaviour [#behaviour]

- The new role appears in [change history](/slim-apis/audit/list-change-history) as an `Access` row with key `roleCreated`. Membership role changes appear as `userRoleChanged` rows. See the [key catalogue](/slim-apis/audit/change-history-keys).

- You cannot create a policy above your own rank. Ranks come from the policy name or its `basedOn` display, compared exactly and ignoring case and surrounding spaces: `System Owner` is the highest, then `Admin`, then every other policy. Project admins rank as System Owner.
- Policy names are not checked for uniqueness. A second policy with the same name is created.
- Ovok adds interactions the apps rely on:
  - `Consent`: `read`, `search`, `create`, `update`, always;
  - `DeviceUseStatement` and `EpisodeOfCare`: `read`, `search`, `create`, `update`, when the policy may create or update `Patient`;
  - `Provenance` and `AuditEvent`: `read`, `search`, when the policy is named `Admin` or `System Owner`.
- `members` are profile references such as `Practitioner/<id>`. Each listed member's membership in your project now points to the new policy, replacing the policy it held before. A member with no membership in your project is skipped.
- You cannot list a member whose current role ranks above yours. A member ranks as every policy their membership holds now (`accessPolicy` and any `access` entries), each ranked by its name. A project admin (`admin: true`) ranks as System Owner.
- The policy and the membership changes commit together. Past 49 membership changes they are written in two steps.
- The policy is then copied by name into each direct child project. A child policy with the exact same name is overwritten with this policy's rules. When there is none, one is created. A failed copy does not fail the request.
- In the single commit, a failure creates nothing: the request answers 409 when another write won the race, and 400 when the FHIR server refuses the write. In the two-step path the policy is created first, so a failed membership change can leave the new policy in place.
- Returns the created policy with its members, as in `GET /v1/slim/policy/{id}`. The rules include the interactions Ovok added.


## Example [#example]

```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/slim/policy' \
  -H "Authorization: Bearer ${OVOK_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
    "policy": {
      "resourceType": "AccessPolicy",
      "name": "Night shift",
      "resource": [{ "resourceType": "Patient", "interaction": ["read", "search"] }]
    },
    "members": [{ "reference": "Practitioner/5b8d2f90-1a3c-4e67-8d4b-7c9e0a2f1b63", "display": "Demo Nurse" }]
  }'
```

## Successful response [#successful-response]

`201` — Access policy created successfully.

```json
{
  "policy": {
    "resourceType": "AccessPolicy",
    "id": "7d3a9e52-6c1b-4f08-b4a7-2e5c8d1f9a36",
    "name": "Night shift",
    "resource": [
      { "resourceType": "Patient", "interaction": ["read", "search"] },
      { "resourceType": "Consent", "interaction": ["read", "search", "create", "update"] }
    ],
    "meta": {
      "project": "1e6b8d30-2c4f-4a95-8d7e-b0a2c4e6f918",
      "author": { "reference": "Practitioner/2c9f4e18-7a5d-4b30-9e61-8d0b3a7c5f24" },
      "lastUpdated": "2026-10-09T09:15:00.000Z"
    }
  },
  "members": [
    { "reference": "Practitioner/5b8d2f90-1a3c-4e67-8d4b-7c9e0a2f1b63", "display": "Demo Nurse" }
  ]
}
```

The response is the policy as read back after the write. It has the same shape as `GET /v1/slim/policy/{id}`. Optional fields are omitted when they have no value. They are not sent as `null`. See [AccessPolicy model and membership](/access-policies/policy-model) for what the rule fields mean.

| Field | Type | Description |
| --- | --- | --- |
| `policy` | `object` | The access policy, as stored. It is the policy resource passed through as is, so the FHIR server can add standard fields that are not listed here (for example `meta.versionId`). |
| `policy.resourceType` | `"AccessPolicy"` | Always `AccessPolicy`. |
| `policy.id` | `string (uuid)` | Policy id. |
| `policy.name` | `string` | Policy name. |
| `policy.resource` | `object[]` | The resource rules. Absent when the policy has none. |
| `policy.resource[].resourceType` | `string` | Resource type the rule covers, for example `Patient`. `*` covers every resource type. |
| `policy.resource[].interaction` | `string[]` | Allowed interactions: `read`, `create`, `update`, `delete`, `search`, `history`, `vread`. Absent when the stored rule has none. |
| `policy.resource[].criteria` | `string` | Optional FHIR search expression that limits which resources the rule applies to. Present only on rules created outside this API. |
| `policy.resource[].readonly` | `boolean` | Optional. `true` limits the rule to read-only behaviour. Present only on rules created outside this API. |
| `policy.meta` | `object` | Resource metadata. |
| `policy.meta.project` | `string (uuid)` | Id of the project the policy belongs to. |
| `policy.meta.author` | `object` | The profile that wrote the policy. |
| `policy.meta.author.reference` | `string` | Reference to the author, for example `Practitioner/<id>`. |
| `policy.meta.lastUpdated` | `string (ISO 8601 date-time)` | When the policy was last written. |
| `members` | `object[]` | The practitioners who hold the policy. Empty when nobody does. Other kinds of profile are not listed. |
| `members[].reference` | `string` | Practitioner reference, `Practitioner/<id>`. |
| `members[].display` | `string` | Display name, from the membership or the practitioner's name. Absent when neither has one. |

## Errors [#errors]

| Status | Meaning |
| --- | --- |
| [`400`](/errors/malformed-request) | The session carries no project or profile, or the FHIR server refused the write. |
| [`401`](/errors/unauthenticated) | The bearer token is missing or invalid. |
| [`403`](/errors/forbidden) | The session is not a practitioner, admin or System Owner session, its access policy lacks a required interaction, the policy ranks above the caller, a member holds a role above the caller, or a membership to change is outside the caller's project. |
| [`409`](/errors/conflict) | A membership change lost a write [`conflict`](/errors/conflict), or the commit conflicted. |
| [`422`](/errors/validation-failed) | The body fails validation, for example `policy.name` is empty, `policy.resource` is missing, or an interaction is not one of the listed values. |
| [`500`](/errors/internal-error) | The write failed unexpectedly, or failed and could not be fully rolled back. |
| [`503`](/errors/service-unavailable) | Your access policy could not be read, or the service is temporarily over capacity. Retry shortly, and honour `Retry-After` when it is present. |
