# Set up a wearable provider

Canonical page: https://docs.ovok.com/api/wearables/set-up-a-wearable-provider

`POST /v1/wearables/providers`

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" }'
```