---
title: "Register a device push token for the current user"
method: POST
path: "/v1/push/subscription/{appId}"
tags: ["Push"]
---

# Register a device push token for the current user

`POST /v1/push/subscription/{appId}`

## Request

- Base URL: `https://api.chat.ethora.com`
- URL: `https://api.chat.ethora.com/v1/push/subscription/{appId}`
- Auth: HTTP bearer

Creates or updates a push subscription for the current authenticated user (jid = req.user.xmppUsername).
Proxies to the configured push service.

## Path parameters

- `appId` string, required

## Request body

- object
  - `registrationToken` string, required: FCM registration token, or a raw APNs/PushKit device token when tokenType is apns/apns-voip
  - `tokenType` 'fcm' | 'apns' | 'apns-voip': 'fcm' (default) - Firebase registration token, delivered via FCM. 'apns' - raw APNs device token, delivered via direct APNs (requires the app's APNs auth key to be uploaded). 'apns-voip' - PushKit VoIP token; registered alongside the device's regular 'apns' subscription and used ONLY for incoming-call pushes (apns-push-type voip, topic bundleId.voip). Regular messages never go to it.
  - `buildOrigin` 'tenant' | 'platform': Which build family issued the token — delivery keys must match the BUILD that produced it, not the tenant. 'tenant' (default) - the tenant's own white-label build; delivered with the keys uploaded for this app. 'platform' - the universal store app; delivered with the platform's keys regardless of tenant.
  - `deviceType` 'android' | 'ios' | 'web', required
  - `pushKey` string: Encrypted pushes: base64 of the device's raw 32-byte X25519 public key. Chat pushes to this token then arrive data-only with their content in a libsodium sealed box for this key (see the push service README, "Encrypted pushes"). An empty string removes a stored key; omitting the field keeps it.
  - `pushKeyAlg` 'sealed-box-x25519': Construction the key is for (default sealed-box-x25519).
  - `pushKeyId` string: Key id returned in every sealed push as `kid`. Default: the first 16 hex characters of SHA-256 over the raw key.

## Response `200`

ok

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `422`: validation error
- `500`: Internal Server Error

---

[API](https://skmtc.dev/ethora/apis/platform-api.md) · [All operations](https://skmtc.dev/ethora/apis/platform-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ethora/apis/platform-api/revisions/01b6e64378ee?raw)