# Register a push device

Canonical page: https://docs.ovok.com/api/push/register-a-push-device

`POST /v1/push/devices`

Registers the device your app runs on for push, under your own profile. Call it after sign-in and again whenever the push token changes. The token is stored once and never returned.

**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

- `token` is the push token the platform gave the app: an FCM registration token, an APNs device token (hex), or an Expo push token. Up to 4,096 printable characters, no spaces.
- `platform` is `ios`, `android` or `web`. Anything else is 422.
- `appId` is optional: the app the token belongs to, such as its bundle or package id.
- A token new to the project answers **201** with `Location: /v1/push/devices/<id>`.
- The same token again answers **200** with the device as it was, and the same `Location`. Registering on every app start is safe.
- A token another profile of the project registered (someone else signed in on this device before) moves to you and answers 201: push for the earlier profile stops reaching this device.
- The project's push provider (`/v1/push/provider`) decides which tokens it can send to. A token the provider later reports as no longer registered is removed on that send.

## Example

```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/push/devices' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
  -H 'Content-Type: application/json' \
  -d '{ "token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]", "platform": "ios", "appId": "com.example.care" }'
```
