Access policies

Create access policy

Create access policy using Ovok’s Slim API.

MethodPath
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

NameTypeRequiredDescription
policyobjectYesThe policy to create.
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[]YesProfiles that get the policy. May be empty.
members[].referencestringYesProfile reference, for example Practitioner/<id>.
members[].displaystringYesDisplay 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 Access row with key roleCreated. Membership role changes appear as userRoleChanged rows. See the key catalogue.

  • 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

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.

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
400The 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 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.
409A membership change lost a write conflict, or the commit conflicted.
422The body fails validation, for example policy.name is empty, policy.resource is missing, 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