Access policies

List access policies

List access policies using Ovok’s Slim API.

MethodPath
GET/v1/slim/policy

Authentication · Access policies

Lists the access policies (roles) of a project, each with the practitioners who hold it. Use it to render a roles table.

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 caller's project (from the token), or projectId when given. projectId must be the caller's project or a direct child of it.

Request

Query parameters

NameTypeRequiredDescription
pageintegerNoZero-based page number. Default 0, minimum 0.
countintegerNoRows per page. Default 20, minimum 1, maximum 100.
sortBy"_id" | "_lastUpdated" | "name"NoSort column. When omitted, no sort is applied.
orderBy"ASC" | "DESC"NoSort direction, used with sortBy. Upper case only. Default ASC.
projectIdstring (uuid)NoProject to list. Default: the caller's project. Must be the caller's project or a direct child of it.
profilestringNoKeep only the policies held by this member, as a reference such as Practitioner/<id>. Exact match.
searchstringNoAccepted, but a non-empty value currently matches no policy. See Behaviour.

Behaviour

  • Each row is { policy, members }. members lists only Practitioner members, as { reference, display }.
  • profile keeps only the policies held by that member, given as a reference such as Practitioner/<id>.
  • sortBy is _id, _lastUpdated or name; orderBy is ASC (default) or DESC. Without sortBy the rows are not sorted, so orderBy has no effect and the order is not guaranteed. Sorting is case-insensitive and treats digits as numbers. Rows with an empty sort value go last in ASC and first in DESC.
  • Paging is in memory: page (default 0) and count (default 20, 1 to 100). total counts the rows after filtering, before paging. A page past the last row returns an empty resources array.
  • search does not narrow the list. Any non-empty value returns total 0 and no rows. Leave it out and filter on your side.
  • A numeric parameter that is not a whole number, or is out of range, is refused with 422. sortBy and orderBy accept only the listed values. Unknown parameters are ignored.
  • Only policies stored in the project are listed. The implicit admin access that a project admin has without any policy is not a policy of the project, so it is never listed, read, updated or deleted through these routes.
  • A session without a project gets 400. A projectId outside your project and its direct children gets 403.

Example

curl -X GET 'https://api.sandbox.ovok.com/v1/slim/policy?sortBy=name&orderBy=ASC&page=0&count=20' \
  -H "Authorization: Bearer ${OVOK_TOKEN}"

Successful response

200 — Access policies retrieved successfully.

{
  "total": 2,
  "resources": [
    {
      "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"] }
        ],
        "meta": {
          "project": "1e6b8d30-2c4f-4a95-8d7e-b0a2c4e6f918",
          "author": { "reference": "Practitioner/5b8d2f90-1a3c-4e67-8d4b-7c9e0a2f1b63" },
          "lastUpdated": "2026-10-01T08:00:00.000Z"
        }
      },
      "members": [
        { "reference": "Practitioner/5b8d2f90-1a3c-4e67-8d4b-7c9e0a2f1b63", "display": "Demo Nurse" }
      ]
    },
    {
      "policy": {
        "resourceType": "AccessPolicy",
        "id": "9a4e1d6c-2b7f-4e83-a5c1-0f8d3b6e2a47",
        "name": "Day shift",
        "resource": [
          { "resourceType": "Patient", "interaction": ["read", "search"] },
          { "resourceType": "Consent", "interaction": ["read", "search", "create", "update"] }
        ],
        "meta": {
          "project": "1e6b8d30-2c4f-4a95-8d7e-b0a2c4e6f918",
          "lastUpdated": "2026-09-28T10:30:00.000Z"
        }
      },
      "members": []
    }
  ]
}

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

Errors

StatusMeaning
400The session carries no project.
401The bearer token is missing or invalid.
403The session is not a practitioner, admin or System Owner session, its access policy lacks Practitioner:create, or projectId is neither the caller's project nor a direct child of it.
422A query parameter fails validation.
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