# Start connecting a wearable provider

Canonical page: https://docs.ovok.com/api/wearables/start-connecting-a-wearable-provider

`POST /v1/wearables/connections/{provider}/authorize`

Starts connecting the signed-in patient's account at a wearable provider. Open the returned `authorizationUrl` in a browser or an auth session (`ASWebAuthenticationSession`, Custom Tabs) whose callback scheme is your patient app's.

**Auth:** bearer token of a patient.
**Scope:** the caller's project and Patient profile (from the token).

## Flow

1. The patient consents on the provider's page.
2. The provider sends the browser to `GET /v1/wearables/oauth/<provider>/callback`.
3. ovok exchanges the code for tokens, stores them encrypted, and redirects the browser (`302`) to the project's patient app at `/wearables/<provider>?result=connected|denied|failed`.

## Behaviour

- The URL is valid for 10 minutes and for one use.
- Polar shares data only for users registered to the app, so ovok registers the patient with Polar right after the code exchange. A patient who has not accepted Polar's mandatory consents is refused, and the callback ends with `result=failed`.
- Connecting a provider the patient is already connected to replaces the stored tokens.
- A provider the project has not set up or has switched off answers `404 PROVIDER_NOT_AVAILABLE`.
- A project with no usable patient app URL (`PATIENT_APP_URL`) answers `409 APP_URL_NOT_CONFIGURED`: the flow would have nowhere to return to.
- When the authorization cannot be stored, the answer is `503 STATE_STORE_UNAVAILABLE` with `Retry-After`.

## Example

```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/wearables/connections/oura/authorize' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```