Register Device
Push Notification Endpoints
Register Device
Register a device to receive push notifications for the authenticated user
Register Device
Registers a push device for the currently authenticated user. Re-registering the same physical device for the same user updates the existing record instead of creating a duplicate.
A device can serve several accounts at once. Registrations are unique per
Returned when a service or master key is used. This endpoint has no
impersonation path by design (see Security note).
Returned when
Returned when the
Returned while the
The registration could not be written. No diagnostic detail is returned;
retry.
Rate limit: 50 requests per 5 minutes per IP. Exceeding it returns
(device, user) pair, so registering a device that is already registered by a different user (e.g. a shared device, or a second account signed in on the same phone) adds a second binding — it does not reassign or replace the first user’s registration. Each bound account then receives its own notifications on that device.
Requires end-user authentication (Authorization: Bearer <accessToken>). Service and master keys are explicitly rejected — this endpoint has no impersonation path by design (see Security note).
Requires the push bundle.
Body Parameters
string
required
The device platform. One of
"ios", "android", or "web".string
The APNs or FCM device token. Required when
platform is "ios" or "android".object
The Web Push subscription object. Required when
platform is "web".Response
Returns200 with the stored device record on success.
Error Responses
No Credential — 401
No Credential — 401
Plain-text
Unauthorized, with no JSON body and no code. Returned when the
request carries no Authorization header at all.Rejected Credential — 403
Rejected Credential — 403
Plain-text
Forbidden, with no JSON body and no code. Returned when the
access token is malformed, has the wrong signature, or has expired — the
common case, since access tokens live 30 minutes. Refresh the access token
and retry; do not treat this as a permanent refusal.Service Key Rejected — 401
Service Key Rejected — 401
Invalid Body — 400
Invalid Body — 400
platform is unrecognized, or when the required token / subscription field is missing for the given platform.Bundle Not Installed — 403
Bundle Not Installed — 403
push bundle is not installed for this project.Bundle Provisioning — 503
Bundle Provisioning — 503
push bundle is mid-install. Retry shortly.Server Error — 500
Server Error — 500
429 with a plain-text message and no code.
Security note
Unlike most other write endpoints, this endpoint does not accept auserId body parameter and cannot be called with a service key. Allowing a backend to register an arbitrary token for an arbitrary user would let it redirect that user’s push notifications to an attacker-controlled device. Registration must always come from the end user’s own session.

