Update access policy
Update access policy using Ovok’s Slim API.
| Method | Path |
|---|---|
PUT | /v1/slim/policy/:id |
Authentication · 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
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | Yes | Access policy id. Must equal policy.id in the 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
-
Changed permissions appear in change history as an
Accessrow with keyrolePermissionsChanged; membership role changes appear asuserRoleChangedrows. No row is written for unchanged permissions or roles. See the key catalogue. -
policy.idmust equal theidin 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 ascriteriaandreadonlythat this route cannot send. The same interactions as on create are added (Consent;DeviceUseStatementandEpisodeOfCarefor policies that create or updatePatient;ProvenanceandAuditEventforAdminandSystem Ownerpolicies). -
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
basedOndisplay, compared exactly and ignoring case and surrounding spaces:System Owner, thenAdmin, 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 (
accessPolicyand anyaccessentries), each ranked by its name. A project admin (admin: true) ranks as System Owner. -
membersis the complete list of holders, as references such asPractitioner/<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
accessentries, 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
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
200 — Access policy updated successfully.
{
"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 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
| Status | Meaning |
|---|---|
400 | 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 | The bearer token is missing or invalid. |
403 | 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 | No access policy has this id. |
409 | A member you remove would be left with no role (move them to another role first), a membership change lost a write conflict, or the commit conflicted. |
422 | 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 | The write failed unexpectedly, or failed and could not be fully rolled back. |
503 | Your access policy could not be read, or the service is temporarily over capacity. Retry shortly, and honour Retry-After when it is present. |
Last updated on