Change the push provider
- Sandbox: available
- On your own host? Choose https://{host} in the playground.
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
providernames the provider set up. Another one is 409PUSH_PROVIDER_MISMATCH: remove the current one withDELETE, then set the new one up withPOST.- Send the fields to change, with the rules of
POST:fcm:secret.apns: any ofsecret,teamId,keyId,bundleIdandenvironment.expo:secret, ornullto 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 502PUSH_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/providerreturns 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.
bearerAuthorizationBearer <JWT>application/json- body
provider*"fcm""fcm"secret*stringThe Firebase service account key: the JSON file, as text. Never returned.
1 <= length <= 10000The provider after the change.
application/json- response
projectId*stringprovider*stringThe provider push is sent through; null when none.
"fcm""apns""expo""relay"settings*What the provider is set up with, never a secret; null when none.
secret*stringThe relay's whsec_ signing secret, answered once when the relay is set up; null otherwise.
curl -X PATCH 'https://api.sandbox.ovok.com/v1/push/provider' \ -H 'Content-Type: application/json' \ -d '{ "provider": "fcm", "secret": "string"}'{ "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).