Skip to main content

Register a device

POST 
/devices

Register a device for push notifications.

Registration is an upsert keyed on (project, token), so calling it on every app launch is safe and idempotent. Re-registering an existing token under a different user_id reassigns the device to that user — the previous association does not persist, so a push addressed to the old user will not reach this device.

user_id is an opaque string you choose. It is stored verbatim with no foreign key, and POST /v1/push matches on exactly that value. No Subscriber record is created for you.

Call this from your backend and derive user_id from the authenticated session rather than the request body.

Two credentials are accepted, and the choice matters for push routing:

  • Application credentials — X-Application-Key + X-Application-Secret (za_*). The device is bound to that application, and pushes to it resolve that application's push provider credentials. Use this when a single project contains more than one app: APNs credentials are bound to a bundle id, so a device registered under the wrong application has its pushes rejected by Apple. The application is taken from the credential and can never be set from the request body.

    Using an environment-scoped key (za_test_pub_* / za_live_pub_*) also binds the device to that environment, which is what lets APNs sandbox and production credentials be configured separately. A legacy application-level key (za_pub_*) binds the application only, and such devices will not match an environment-scoped push config.

  • Project secret API key (zy_*) — the device is not bound to any application and resolves the project-level push provider config. This is the historical behaviour and remains supported.

Request​

Responses​

Device registered