Push

Change the push provider

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

Changes the credentials or settings of the push provider your current project has set up. The result is checked with the provider before it is stored, as POST does.

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

Behaviour

  • provider names the provider set up. Another one is 409 PUSH_PROVIDER_MISMATCH: remove the current one with DELETE, then set the new one up with POST.
  • Send the fields to change, with the rules of POST:
    • fcm: secret.
    • apns: any of secret, teamId, keyId, bundleId and environment.
    • expo: secret, or null to stop sending an access token.
    • relay: url. The signing secret stays as it is.
  • No provider set up is 404 PROVIDER_NOT_CONFIGURED.
  • A refusal from the check is 422 INVALID_CREDENTIALS, an unreachable provider 502 PUSH_PROVIDER_UNAVAILABLE; nothing is stored either way.
  • When the server has no encryption key, nothing is stored and the answer is 503 ENCRYPTION_UNAVAILABLE.
  • The answer has the provider as GET /v1/push/provider returns it.

Example

curl -X PATCH 'https://api.sandbox.ovok.com/v1/push/provider' \  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \  -H 'Content-Type: application/json' \  -d '{ "provider": "apns", "environment": "production" }'

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

Authorization

bearer
headerAuthorizationBearer <JWT>

Request Body

application/json
  1. body
provider*"fcm"
Value in"fcm"
secret*string

The Firebase service account key: the JSON file, as text. Never returned.

Length1 <= length <= 10000

Response Body

The provider after the change.

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 PATCH 'https://api.sandbox.ovok.com/v1/push/provider' \  -H 'Content-Type: application/json' \  -d '{  "provider": "fcm",  "secret": "string"}'
Example Response
{  "projectId": "string",  "provider": "fcm",  "settings": {    "property1": "string",    "property2": "string"  },  "secret": "string"}

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

Remove the push provider DELETE

Removes the push provider your current project has set up, with its credentials. No push is sent until one is set up again. **Scope:** the caller's project (from the token). ## Behaviour - The answer is 204. - No provider set up is 404 `PROVIDER_NOT_CONFIGURED`. - Registered devices are kept, so a new provider sends to them at once. - A 409 means the project changed while the server wrote. Read it again and retry. ## Example ```bash curl -X DELETE 'https://api.sandbox.ovok.com/v1/push/provider' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ``` **Who can call it:** a project admin. See [roles](/access-policies#who-can-call-a-route).