Skip to main content
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 (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

Returns 200 with the stored device record on success.

Error Responses

Plain-text Unauthorized, with no JSON body and no code. Returned when the request carries no Authorization header at all.
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.
Returned when a service or master key is used. This endpoint has no impersonation path by design (see Security note).
Returned when platform is unrecognized, or when the required token / subscription field is missing for the given platform.
Returned when the push bundle is not installed for this project.
Returned while the push bundle is mid-install. Retry shortly.
The registration could not be written. No diagnostic detail is returned; retry.
Rate limit: 50 requests per 5 minutes per IP. Exceeding it returns 429 with a plain-text message and no code.

Security note

Unlike most other write endpoints, this endpoint does not accept a userId 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.

See Also