Push

Get the project's push provider

  • Sandbox: available
  • On your own host? Choose https://{host} in the playground.
GET
/v1/push/provider

Returns the provider your current project sends push through, and what it is set up with. It never returns a secret.

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

Behaviour

  • provider is fcm, apns, expo or relay, or null when none is set up.
  • settings shows the setup without its secret, or null:
    • fcm: firebaseProjectId and clientEmail from the service account key.
    • apns: teamId, keyId, bundleId and environment.
    • expo: accessToken, whether one is stored.
    • relay: url.
  • secret is always null here. A relay's signing secret is shown once, when it is set up.
  • A config stored with another server's key reads as not set up; set it up again with POST.

Example

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

Who can call it: a project admin. See roles.

Authorization

bearer
headerAuthorizationBearer <JWT>

Response Body

Which provider push goes through and its settings. Never a secret.

application/json
  1. response
projectId*string
provider*string

The provider push is sent through; null when none.

Value in"fcm""apns""expo""relay"
settings*

What the provider is set up with, never a secret; null when none.

secret*string

The relay's whsec_ signing secret, answered once when the relay is set up; null otherwise.

Example Request
curl -X GET 'https://api.sandbox.ovok.com/v1/push/provider'
Example Response
{  "projectId": "string",  "provider": "fcm",  "settings": {    "property1": "string",    "property2": "string"  },  "secret": "string"}

Remove a push device DELETE

Removes one of your push devices: it gets no more push. Call it on sign-out. **Scope:** the caller's own profile in the caller's project (from the token). A Patient, Practitioner or RelatedPerson session only; any other is 403 `PROFILE_NOT_ALLOWED`. ## Behaviour - The answer is 204. - A device that is not yours, is in another project, or is already gone answers 404 `PUSH_DEVICE_NOT_FOUND`, the same in each case. - An id that is not a UUID is 422. - Deleting the account removes its devices too. ## Example ```bash curl -X DELETE 'https://api.sandbox.ovok.com/v1/push/devices/c3499c27-2973-0a7f-807e-fb8676a92dcb' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```

Set up the push provider POST

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).