Create access policy
Create access policy using Ovok’s Slim API.
| Method | Path |
|---|---|
POST | /v1/slim/policy |
Authentication · 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
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
-
The new role appears in change history as an
Accessrow with keyroleCreated. Membership role changes appear asuserRoleChangedrows. See the key catalogue. -
You cannot create a policy above your own rank. Ranks come from the policy name or its
basedOndisplay, compared exactly and ignoring case and surrounding spaces:System Owneris the highest, thenAdmin, 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;DeviceUseStatementandEpisodeOfCare:read,search,create,update, when the policy may create or updatePatient;ProvenanceandAuditEvent:read,search, when the policy is namedAdminorSystem Owner.
-
membersare profile references such asPractitioner/<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 (
accessPolicyand anyaccessentries), 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
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
201 — Access policy created successfully.
{
"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 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 | 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 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 | A membership change lost a write conflict, or the commit conflicted. |
422 | 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 | 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