# Update access policy

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

| Method | Path |
| --- | --- |
| `PUT` | `/v1/slim/policy/:id` |

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

Replaces an access policy (role) of your project and sets exactly which practitioners hold it.

**Auth:** Bearer token for a practitioner, project admin or System Owner session. The caller's access policy must grant `Practitioner:create`, the right to invite users (project admins skip this check).
**Scope:** The policy must belong to the caller's project (from the token). Policies of parent or child projects can be read but not updated here.

## Request [#request]

### Path parameters [#path-parameters]

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string (uuid)` | Yes | Access policy id. Must equal `policy.id` in the body. |

### Body [#body]

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `policy` | `object` | Yes | The new content of the policy. |
| `policy.id` | `string (uuid)` | Yes | Policy id. Must equal the `id` in the path. |
| `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 | The complete list of holders. May be empty. |
| `members[].reference` | `string` | Yes | Profile reference, for example `Practitioner/<id>`. |
| `members[].display` | `string` | No | Display name. Not stored: the response takes names from the practitioner profile. |

Any other field is ignored. This includes rule fields such as `criteria` and `readonly`.

## Behaviour [#behaviour]

- Changed permissions appear in [change history](/slim-apis/audit/list-change-history) as an `Access` row with key `rolePermissionsChanged`; membership role changes appear as `userRoleChanged` rows. No row is written for unchanged permissions or roles. See the [key catalogue](/slim-apis/audit/change-history-keys).

- `policy.id` must equal the `id` in the path.
- The policy is replaced as a whole with `policy`. Anything you do not send is removed from the stored policy, including rule fields such as `criteria` and `readonly` that this route cannot send. The same interactions as on create are added (`Consent`; `DeviceUseStatement` and `EpisodeOfCare` for policies that create or update `Patient`; `Provenance` and `AuditEvent` for `Admin` and `System Owner` policies).
- You cannot update a policy that ranks above you, nor rename one to a rank above you. Ranks come from the policy name or its `basedOn` display, compared exactly and ignoring case and surrounding spaces: `System Owner`, then `Admin`, then every other policy. Project admins rank as System Owner.
- Policy names are not checked for uniqueness.
- A policy of another project answers 403, also when it is in your parent or a child project. An id that matches no policy answers 404.
- You cannot add or remove 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.
- `members` is the complete list of holders, as references such as `Practitioner/<id>`:
  - a listed member's membership in your project now points to this policy, replacing the one it held;
  - a current holder not listed loses the policy. A membership without a policy is treated as full access, so if that would leave them with none (no `access` entries, not a project admin), the request answers 409: move them to another role first;
  - you cannot remove yourself.
- The policy and the membership changes commit together. Past 49 membership changes they are written in two steps: the policy is replaced first, so a failed membership change can leave the new policy content in place. Within the limit, a failure changes nothing.
- The updated policy is then copied by name into each direct child project, also when it was renamed. Child policies with the exact same name, or the previous name after a rename, are overwritten with this policy's rules. When there is none, one is created. A failed copy does not fail the request.
- Returns the updated policy with its members. The rules include the interactions Ovok added.


## Example [#example]

```bash
curl -X PUT 'https://api.sandbox.ovok.com/v1/slim/policy/3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21' \
  -H "Authorization: Bearer ${OVOK_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
    "policy": {
      "resourceType": "AccessPolicy",
      "id": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21",
      "name": "Night shift",
      "resource": [{ "resourceType": "Patient", "interaction": ["read", "search", "update"] }]
    },
    "members": [{ "reference": "Practitioner/5b8d2f90-1a3c-4e67-8d4b-7c9e0a2f1b63" }]
  }'
```

## Successful response [#successful-response]

`200` — Access policy updated successfully.

```json
{
  "policy": {
    "resourceType": "AccessPolicy",
    "id": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21",
    "name": "Night shift",
    "resource": [
      { "resourceType": "Patient", "interaction": ["read", "search", "update"] },
      { "resourceType": "Consent", "interaction": ["read", "search", "create", "update"] },
      { "resourceType": "DeviceUseStatement", "interaction": ["read", "search", "create", "update"] },
      { "resourceType": "EpisodeOfCare", "interaction": ["read", "search", "create", "update"] }
    ],
    "meta": {
      "project": "1e6b8d30-2c4f-4a95-8d7e-b0a2c4e6f918",
      "author": { "reference": "Practitioner/2c9f4e18-7a5d-4b30-9e61-8d0b3a7c5f24" },
      "lastUpdated": "2026-10-09T09:20: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) | `policy.id` differs from the path, you would remove yourself, 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 `Practitioner:create`, the policy is not in the caller's project, the policy ranks above the caller before or after the change, or a member added or removed holds a role above the caller. |
| [`404`](/errors/not-found) | No access policy has this id. |
| [`409`](/errors/conflict) | A member you remove would be left with no role (move them to another role first), a membership change lost a write [`conflict`](/errors/conflict), or the commit conflicted. |
| [`422`](/errors/validation-failed) | `id` is not a UUID, or the body fails validation, for example `policy.id` is missing or not a UUID, 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. |
