Register an installation
Register the device on sign-in, before any message can be addressed to it.
POST /api/push/registerInstallation
X-Push-App-Key: <application key>
Content-Type: application/json
{
"externalUserId": "operator-497",
"firebaseInstallationId": "fA9kQ2xRTb2mLp0WYs4nEv",
"fcmToken": "fA9kQ2xRTb2mLp0WYs4nEv:APA91bH3xK…",
"platform": "android",
"notificationsEnabled": true
}
Fields
| Field | Required | Notes |
|---|---|---|
externalUserId | yes | Stable user id. One user may hold many installations. Namespace it — operator-497, client-497 — because operator and client ids live in the same space and would otherwise collide. |
firebaseInstallationId | yes | From the Installations SDK. Upsert key together with the application. |
fcmToken | in practice | From the Messaging SDK. The only value the send API can deliver to. Optional in the schema so older clients keep working, but an installation without it is undeliverable. |
platform | yes | "android" or "ios", lowercase only. |
notificationsEnabled | no | Defaults to true. false excludes the installation from sending. |
Responses
| Code | Meaning |
|---|---|
200 | Accepted |
400 | Invalid fields |
401 | Unknown or inactive application |
Send both identifiers
The FID stays the upsert key; the token is what gets sent to. Since the token rotates independently of the FID, every registration must overwrite the stored token.
Sending only the installation id is the single most common integration failure: the FCM v1 API accepts only the registration token in message.token, and a bare FID is rejected. See the error catalogue for how that surfaces.
Re-registration
Re-registering the same installation id under a different externalUserId rebinds it — this is what makes logout-then-login work.
Under the same user it refreshes platform, subscription and last_seen_at, and reactivates the installation.
Take the id and the token independently
If getToken() throws — and on iOS it throws routinely until the APNs token arrives — a shared try/catch returns a null installation id as well. Callers that skip registration without an id then send nothing at all, and the failure looks like the app never ran.
A missing token costs delivery. It must not also cost the registration.