Projects
A project is the unit of tenancy on Ovok. Your bearer token is scoped to one project, and most routes work on that project. A project is entered by signing in with its tenant code.
A sub-project, also called a child project, is a project linked below another project, its parent. A project has at most one parent. Projects can be nested: a sub-project can have sub-projects of its own. The routes on these pages report one level at a time, so a project lists its direct sub-projects, not its grandchildren.
Use the routes here to find the projects you administer, and to create and delete sub-projects. See Authentication for tokens.
Which route do I need?
| I want to… | Who calls | Route | Page |
|---|---|---|---|
| List every project I administer, with its tenant code | A practitioner or admin | GET /v1/projects | List administered projects |
| See my project's parent and its direct sub-projects | A project admin | GET /v1/sub-project | List sub-projects |
| Create a sub-project of my project | A project admin | POST /v1/sub-project | Create a sub-project |
| Delete an empty sub-project of my project | A project admin | DELETE /v1/sub-project/:subProjectId | Delete a sub-project |
| Add a colleague to my project | A project admin | POST /v1/projects/me/members | Invite a team member |
| Change a project's features or settings | A project admin | See the page | Settings and features |
Routes
GET /v1/projects— List administered projectsGET /v1/sub-project— List sub-projectsPOST /v1/sub-project— Create a sub-projectDELETE /v1/sub-project/:subProjectId— Delete a sub-project
The three sub-project routes also answer without /v1, for example POST /sub-project. GET /v1/projects answers only with /v1.
How the routes fit together
GET /v1/projects is the only route that looks across projects. It reads your own memberships, so it works from a practitioner session on any project you belong to. Every other route here, and most routes in these docs, works on the project in your token.
A typical flow for a sub-project, with a user token:
- Create it with
POST /v1/sub-project. With a user token the response carries no project id. - Find it with
GET /v1/projects. The row carries itstenantCode. - Sign in again with that
tenantCode. The token you get is scoped to the new project. - Set it up. Features and settings apply to the project in the token, and team members are added with Invite a team member.
- When it is no longer needed and holds no residents, devices or locations, delete it with
DELETE /v1/sub-project/:subProjectId.
A client application token has no user behind it. It gets projectId in the create response, and it cannot call GET /v1/projects, which needs a user.
Sub-projects and Slim project routes
The Slim APIs have a "Projects" group, and two of its routes do the same jobs as routes here. They are not interchangeable.
POST /v1/slim/project/child | POST /v1/sub-project | |
|---|---|---|
| Who | Project admin | Project admin. A super admin may name another parent. |
| Body | name, address, contact, settings | name, extension, parentProjectId for super admins |
| Access policies | Copies every access policy of your project. Without one the request is refused with 424. | Copies none at creation. Later changes made through the Slim access-policy routes are copied by name. |
| Project settings | Sets login, invitation and registration settings | Sets none. Each starts unset. |
| Thresholds | Seeded from the global defaults | Not seeded |
| Same name under one parent | Refused with 422 | Allowed. Only concurrent creates are refused with 409. |
| Response | { "projectId": "...", "success": true } | { "success": true } for a user, with projectId added for a client application |
Use the Slim route to set up a customer or site: it copies your access policies and seeds thresholds. Use /v1/sub-project when you only need the project, its tenant and its admin.
GET /v1/slim/project/child | GET /v1/sub-project | |
|---|---|---|
| Who | Practitioner, admin or System Owner, with AccessPolicy:read | Project admin |
| Returns | Your project, its parent and its direct children, each with name, address, contact and settings | Ids only: your project, its parent and its direct children |
Deleting is the same. DELETE /v1/slim/project/child/:subProjectId and DELETE /v1/sub-project/:subProjectId run the same delete.
The other Slim project routes have no equivalent here: get a project, update a project, list child projects with device counts, list current project users and list project users.
Members, settings and features
- Members. The practitioners of your project are listed and managed under
/v1/projects/me/members. Those routes are documented in Invite a team member and Invitations, not here. - Features and settings. A project created with
POST /v1/sub-projecthas the standard featuresbots,cron,email,transaction-bundlesandwebsocket-subscriptions, and no setting stored. Change them with the routes in Settings and features, while signed in to that project. - Access policies. The routes here check your role, not an access policy permission. See Access policies for how roles work in the rest of the API.