# List access policies

Canonical page: https://docs.ovok.com/slim-apis/policy/list-access-policies

| Method | Path |
| --- | --- |
| `GET` | `/v1/slim/policy` |

[Authentication](/authentication) · [Access policies](/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 [#request]

### Query parameters [#query-parameters]

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | `integer` | No | Zero-based page number. Default `0`, minimum `0`. |
| `count` | `integer` | No | Rows per page. Default `20`, minimum `1`, maximum `100`. |
| `sortBy` | `"_id"` \| `"_lastUpdated"` \| `"name"` | No | Sort column. When omitted, no sort is applied. |
| `orderBy` | `"ASC"` \| `"DESC"` | No | Sort direction, used with `sortBy`. Upper case only. Default `ASC`. |
| `projectId` | `string (uuid)` | No | Project to list. Default: the caller's project. Must be the caller's project or a direct child of it. |
| `profile` | `string` | No | Keep only the policies held by this member, as a reference such as `Practitioner/<id>`. Exact match. |
| `search` | `string` | No | Accepted, but a non-empty value currently matches no policy. See Behaviour. |

## 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 [#example]

```bash
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 [#successful-response]

`200` — Access policies retrieved successfully.

```json
{
  "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](/access-policies/policy-model) for what the rule fields mean.

| Field | Type | Description |
| --- | --- | --- |
| `total` | `integer` | Number of rows after filtering, across all pages. |
| `resources` | `object[]` | The rows of this page. Each row has the shape of the single-policy response. |
| `resources[].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`). |
| `resources[].policy.resourceType` | `"AccessPolicy"` | Always `AccessPolicy`. |
| `resources[].policy.id` | `string (uuid)` | Policy id. |
| `resources[].policy.name` | `string` | Policy name. |
| `resources[].policy.resource` | `object[]` | The resource rules. Absent when the policy has none. |
| `resources[].policy.resource[].resourceType` | `string` | Resource type the rule covers, for example `Patient`. `*` covers every resource type. |
| `resources[].policy.resource[].interaction` | `string[]` | Allowed interactions: `read`, `create`, `update`, `delete`, `search`, `history`, `vread`. Absent when the stored rule has none. |
| `resources[].policy.resource[].criteria` | `string` | Optional FHIR search expression that limits which resources the rule applies to. Present only on rules created outside this API. |
| `resources[].policy.resource[].readonly` | `boolean` | Optional. `true` limits the rule to read-only behaviour. Present only on rules created outside this API. |
| `resources[].policy.meta` | `object` | Resource metadata. |
| `resources[].policy.meta.project` | `string (uuid)` | Id of the project the policy belongs to. |
| `resources[].policy.meta.author` | `object` | The profile that wrote the policy. |
| `resources[].policy.meta.author.reference` | `string` | Reference to the author, for example `Practitioner/<id>`. |
| `resources[].policy.meta.lastUpdated` | `string (ISO 8601 date-time)` | When the policy was last written. |
| `resources[].members` | `object[]` | The practitioners who hold the policy. Empty when nobody does. Other kinds of profile are not listed. |
| `resources[].members[].reference` | `string` | Practitioner reference, `Practitioner/<id>`. |
| `resources[].members[].display` | `string` | Display name, from the membership or the practitioner's name. Absent when neither has one. |

## Errors [#errors]

| Status | Meaning |
| --- | --- |
| [`400`](/errors/malformed-request) | The session carries no project. |
| [`401`](/errors/unauthenticated) | The bearer token is missing or invalid. |
| [`403`](/errors/forbidden) | The 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. |
| [`422`](/errors/validation-failed) | A query parameter fails validation. |
| [`503`](/errors/service-unavailable) | Your access policy could not be read, or the service is temporarily over capacity. Retry shortly, and honour `Retry-After` when it is present. |
