List administered projects

Method	Path
GET	/v1/projects

Authentication · Projects

Lists every project in which you are an admin, with the tenant code of each. Every other route works on the single project in your token. Use this one to build a project picker.

Auth: Bearer token. The caller must be a practitioner, an admin, a super admin, or hold the "System Owner" access policy. You do not need to be an admin of the project in your token. The session must belong to a user, so a client application session is refused. Scope: Your own user. The list is built from your Practitioner memberships across all projects, and keeps only those where the membership is an admin one. You never see anyone else's projects.

Request

Query parameters

Name	Type	Required	Description
page	integer	No	Zero-based page number. Default 0, minimum 0.
count	integer	No	Projects per page. Default 20, minimum 1, maximum 100.

Behaviour

• Only memberships where you are an admin count. A project where you are a plain member is not listed.
• There is one row per project, even when you hold two memberships on it.
• Rows follow the order of your memberships. No sort is applied, so sort on your side if you need one.
• page and count page over the projects. total is the number of projects you administer, not the number of memberships. A page past the end returns an empty resources array.
• tenantCode is null for a project that has none.
• name is null when the project can no longer be read. The row is kept, so the list stays consistent with total.
• isMainProject is true for a project with no parent and false for a child. It is null when the project hierarchy could not be read. Treat null as "unknown" and show a flat list, not as true.
• parentProjectId is set only when the parent is also a project you administer. Otherwise it is null, including for a project with no parent. This lets a picker group children under a parent it is also listing.
• To enter one of these projects, sign in again and send its tenantCode in step 3 of practitioner sign-in (POST /auth/tenant/Practitioner/login/token). A token is scoped to one project.
• No access policy permission is checked beyond the role above. The route only reads your own memberships.

Example

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

Successful response

200 — One page of the projects you administer.

{
  "total": 2,
  "page": 0,
  "count": 20,
  "resources": [
    {
      "projectId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21",
      "name": "Example Health Group",
      "tenantCode": "example-health-group",
      "isMainProject": true,
      "parentProjectId": null
    },
    {
      "projectId": "8c5e7a21-4b9d-4f36-a1c8-0d2e6b9f3a54",
      "name": "Example Clinic North",
      "tenantCode": "example-clinic-north",
      "isMainProject": false,
      "parentProjectId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21"
    }
  ]
}

Field	Type	Description
total	integer	Number of projects you administer, across all pages.
page	integer	Page number of this response.
count	integer	Page size you asked for. The page can hold fewer rows.
resources	object[]	The projects of this page.
resources[].projectId	string (uuid)	Project id.
resources[].name	string | null	Project name. null when the project can no longer be read.
resources[].tenantCode	string | null	Code that selects the project at sign-in. null when the project has none.
resources[].isMainProject	boolean | null	true when the project has no parent, false when it is a child, null when the hierarchy could not be read.
resources[].parentProjectId	string (uuid) | null	The parent, only when you administer it too.

Errors

Status	Meaning
401	Bearer token is missing, invalid, revoked or expired, or the session has no user, as with a client application.
403	The session is not a practitioner, admin, super admin or System Owner session.
422	page or count fails validation: not a number, page below 0, or count outside 1 to 100.
429	Too many requests. Retry after a short wait.