# Set up the push provider

Canonical page: https://docs.ovok.com/api/push/set-up-the-push-provider

`POST /v1/push/provider`

Sets up the provider your current project sends push through. The credentials are checked with the provider first, then stored encrypted with a key of the project's own, and never returned.

**Scope:** the caller's project (from the token).

## Behaviour

- `provider` picks the body:
  - `fcm`: `secret` is the Firebase service account key, the JSON file as text. Sends to Android, iOS and web tokens.
  - `apns`: `secret` is the `.p8` auth key (PEM), with `teamId`, `keyId`, `bundleId` (the APNs topic) and `environment` (`production` or `sandbox`). Sends to iOS tokens.
  - `expo`: `secret` is an Expo access token, or `null` (the default) when the Expo project does not require one. Sends to Expo push tokens.
  - `relay`: `url`, an https URL on a public host. Use it for any other provider (OneSignal, SNS, an in-house gateway): ovok POSTs one `push.send` per person, signed with Standard Webhooks, and your endpoint sends it on.
- The check before storing: FCM exchanges the key for an access token with Google, APNs signs a token with the key, and the relay's host must resolve to public addresses only. A refusal is 422 `INVALID_CREDENTIALS`. A provider that cannot be reached is 502 `PUSH_PROVIDER_UNAVAILABLE`, and nothing is stored.
- For a relay, the answer carries `secret`, the `whsec_` key the deliveries are signed with. It is shown this once. To get a new one, remove the relay and set it up again.
- A project sends through one provider. One already set up is 409 `PROVIDER_CONFIGURED`: change it with `PATCH /v1/push/provider`, or remove it with `DELETE` first.
- When the server has no encryption key, nothing is stored and the answer is 503 `ENCRYPTION_UNAVAILABLE`.
- A 409 without a code means the project changed while the server wrote. Read it again and retry.
- The answer is 201, with the provider as `GET /v1/push/provider` returns it.

## The relay call

```http
POST <url>
webhook-id: msg_…
webhook-timestamp: <unix seconds>
webhook-signature: v1,<base64 HMAC-SHA256>
Content-Type: application/json

{ "type": "push.send",
  "data": { "recipient": { "reference": "Practitioner/…" },
            "devices": [{ "id": "…", "token": "…", "platform": "ios" }],
            "notification": { "title": "…", "body": "…" },
            "data": { … } } }
```

Answer 2xx when sent, 410 when the person's devices are no longer registered (they are removed), or 429 or 5xx to be retried.

## Example

```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/push/provider' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
  -H 'Content-Type: application/json' \
  -d '{ "provider": "relay", "url": "https://push.example.com/ovok" }'
```

**Who can call it:** a project admin. See [roles](/access-policies#who-can-call-a-route).