Access policies

Update access policy

Update access policy using Ovok’s Slim API.

MethodPath
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

NameTypeRequiredDescription
idstring (uuid)YesAccess policy id. Must equal policy.id in the body.

Body

NameTypeRequiredDescription
policyobjectYesThe new content of the policy.
policy.idstring (uuid)YesPolicy id. Must equal the id in the path.
policy.namestringYesPolicy name, 1 to 255 characters. The name also decides the rank of the policy (see Behaviour).
policy.resourceType"AccessPolicy"YesMust be AccessPolicy.
policy.resourceobject[]YesThe resource rules. May be empty.
policy.resource[].resourceTypestringYesResource type the rule covers, 1 to 255 characters, for example Patient. * covers every resource type.
policy.resource[].interactionstring[]YesAllowed interactions, each one of read, create, update, delete, search, history, vread. May be empty.
membersobject[]YesThe complete list of holders. May be empty.
members[].referencestringYesProfile reference, for example Practitioner/<id>.
members[].displaystringNoDisplay 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 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.

  • 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

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.

FieldTypeDescription
policyobjectThe 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.idstring (uuid)Policy id.
policy.namestringPolicy name.
policy.resourceobject[]The resource rules. Absent when the policy has none.
policy.resource[].resourceTypestringResource type the rule covers, for example Patient. * covers every resource type.
policy.resource[].interactionstring[]Allowed interactions: read, create, update, delete, search, history, vread. Absent when the stored rule has none.
policy.resource[].criteriastringOptional FHIR search expression that limits which resources the rule applies to. Present only on rules created outside this API.
policy.resource[].readonlybooleanOptional. true limits the rule to read-only behaviour. Present only on rules created outside this API.
policy.metaobjectResource metadata.
policy.meta.projectstring (uuid)Id of the project the policy belongs to.
policy.meta.authorobjectThe profile that wrote the policy.
policy.meta.author.referencestringReference to the author, for example Practitioner/<id>.
policy.meta.lastUpdatedstring (ISO 8601 date-time)When the policy was last written.
membersobject[]The practitioners who hold the policy. Empty when nobody does. Other kinds of profile are not listed.
members[].referencestringPractitioner reference, Practitioner/<id>.
members[].displaystringDisplay name, from the membership or the practitioner's name. Absent when neither has one.

Errors

StatusMeaning
400policy.id differs from the path, you would remove yourself, the session carries no project or profile, or the FHIR server refused the write.
401The bearer token is missing or invalid.
403The 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.
404No access policy has this id.
409A 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.
422id 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.
500The write failed unexpectedly, or failed and could not be fully rolled back.
503Your 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

On this page