OVOK DOCS
Get startedOvokSignalsSDKsGuidesAPI referenceDeveloper resources
Wearables

List the project's wearable providers

  • Sandbox: available
  • Staging: available
  • Production: unknown
GET
/v1/wearables/providers

Returns every cloud wearable provider ovok supports, and whether your current project has set each one up. It never returns a secret.

Auth: bearer token of a project admin. The caller must also be a Practitioner, an admin or hold the System Owner access policy. Scope: the caller's project (from the token).

Behaviour

  • providers lists oura, whoop, strava, withings, polar, suunto, garmin and ultrahuman.
  • configured is true when the project holds OAuth credentials for the provider that this server can read. Credentials stored with another key read as not configured; set them up again with POST.
  • enabled is true when the provider is configured and switched on. Only then can the project's patients connect it.
  • clientId is the OAuth client ID, or null.
  • redirectUri is the callback URL to register in the provider's developer portal, the same for every project. It is null when this server has no public base URL.
  • webhookUrl is where the provider sends notifications of new data, unique to the project. For Withings it ends in a per-project token that proves a notification's origin, so only admins see it; keep it private. Paste it where the provider's portal asks for one (Suunto). For Withings and Polar it is for information only: ovok registers it itself. It is null when the provider sends no notifications (Oura, Whoop, Strava, Garmin and Ultrahuman for now), is not set up, or this server has no public base URL. See POST /v1/wearables/webhooks/<projectId>/<provider>.
  • webhookReady is true when ovok holds the secret that checks the provider's notifications: Polar's signing key from its webhook setup, the secret ovok makes for Withings, or Suunto's webhookSecret. It is false until then, so a Polar webhook setup that failed shows here; save Polar again to retry. It is null when the provider sends no notifications.

Example

curl -X GET 'https://api.sandbox.ovok.com/v1/wearables/providers' \  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'

Authorization

bearer
headerAuthorizationBearer <JWT>

Response Body

Every provider, set up or not, with the callback and webhook URLs to register. Never a client or webhook secret; Withings' webhookUrl holds a per-project token, for admins only.

application/json
  1. response
providers*array<>
Example Request
curl -X GET 'https://api.sandbox.ovok.com/v1/wearables/providers'
Example Response
{  "providers": [    {      "provider": "oura",      "configured": true,      "enabled": true,      "clientId": "string",      "redirectUri": "string",      "webhookUrl": "string",      "webhookReady": true    }  ]}

Send notifications to video call participants POST

Tells the participants of a video call Appointment that the call is active, and lets them join on their own. A Practitioner calls it when they start the call. **Auth:** bearer token. The caller must be a Practitioner, an admin or a super admin, or hold the "System Owner" access policy. **Scope:** the caller's project (from the token). ## Behaviour - Creates the access permission for the Appointment: a `CommunicationRequest` with the caller as sender and every Appointment participant as recipient. If one already exists for the Appointment, it is replaced. - Patients need this permission to get a join link from `POST /video-call/livekit/user-access/{appointmentId}`. - Queues a real-time event, `/video-call/livekit/notification/active-call`, for each participant who is not already in the LiveKit room. The event carries the sender's name, the Appointment id, description, start and end. Connect to the Ovok events socket to receive it. - The route returns once the event is queued, not when it is delivered. The response is an `OperationOutcome` with severity `information`. ## Example ```bash curl -X POST 'https://api.sandbox.ovok.com/video-call/livekit/notification/active-call/c3499c27-2973-0a7f-807e-fb8676a92dcb' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```

Set up a wearable provider POST

Stores your project's OAuth app at a wearable provider, so the project's patients can connect their accounts. **Auth:** bearer token of a project admin. **Scope:** the caller's project (from the token). ## Before you call it 1. Register an app in the provider's developer program. Garmin, Suunto and Polar approve apps before they work. For Suunto, subscribe the app to the Cloud API product to get its subscription key, both shown on your Suunto profile page. 2. Set its redirect URL to the provider's `redirectUri` from `GET /v1/wearables/providers`. ## Behaviour - `clientId` and `secret` are the app's OAuth client ID and secret. `secret` is never returned. - `subscriptionKey` is required for Suunto (its API-management subscription key) and refused for every other provider. - `webhookSecret` is Suunto's notification secret, the one set beside its notification URL in the Suunto developer portal. It is optional, never returned, and refused for every other provider with `422 WEBHOOK_SECRET_NOT_USED`. Without it, ovok refuses Suunto's notifications and syncs Suunto only daily and on demand. - `enabled` defaults to `true`. - The credentials are encrypted before they are stored. A server that cannot encrypt answers `501` and stores nothing. - For Polar, when `enabled` is `true`, ovok then creates the client's webhook at Polar for the `SLEEP` and `ACTIVITY_SUMMARY` events, pointing at `webhookUrl`. Polar first sends it a `PING`, which ovok answers. ovok keeps the webhook's signing key with the credentials, encrypted and never returned. Should this fail, the credentials stay stored, `webhookReady` answers `false`, and saving them again retries. - A Polar client has one webhook. If it has one already for this project, ovok points it at `webhookUrl` and switches it back on. When ovok does not hold that webhook's signing key, which Polar shows only once, ovok replaces the webhook to get a new key. A webhook pointing at another project, or anywhere else, is left alone: `webhookReady` stays `false`; give each project its own Polar client. - Withings with the client ID of ovok's own Withings device integration answers `422 CLIENT_ID_RESERVED`: register an app of your own. - A provider already set up answers `409 PROVIDER_CONFIGURED`; change it with `PATCH`. A project changed by someone else while this request wrote also answers `409`; read it again and retry. - The answer is `201` with a `Location` header naming the provider. ## Example ```bash curl -X POST 'https://api.sandbox.ovok.com/v1/wearables/providers' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \ -H 'Content-Type: application/json' \ -d '{ "provider": "oura", "clientId": "your-client-id", "secret": "your-client-secret" }' ```