# Register a device for FCM push notifications

> For the complete documentation index, see [llms.txt](https://bsvblockchain.com/docs/llms.txt).

**POST** `/registerDevice`

Base URL: `https://{host}`

Stores or refreshes an FCM token for the authenticated identity. A
token already owned by another identity cannot be reassigned through
this route. Re-registering a token for the same identity updates its
device metadata and last-used timestamp.

## Authorization

- x-bsv-auth-identity-key (apiKey in header)

## Body

Content type: `application/json`

- `fcmToken` (string, required)
  Firebase Cloud Messaging registration token.
- `deviceId` (string)
  Optional caller-supplied device identifier.
- `platform` ("ios" | "android" | "web")
  Device platform.

Example:

```json
{
  "fcmToken": "string",
  "deviceId": "string",
  "platform": "ios"
}
```

## Responses

### 200

Device registered (or updated) successfully.

- `status` ("success", required)
- `message` (string, required)
- `deviceId` (integer, required)
  Database row ID of the registration record.

Example:

```json
{
  "status": "success",
  "message": "string",
  "deviceId": 0
}
```

### 400

Invalid request parameters.
Codes: `ERR_INVALID_FCM_TOKEN`, `ERR_INVALID_PLATFORM`

- `status` ("error", required)
- `code` (string, required)
  Machine-readable error code (see specs/errors.md).
- `description` (string, required)
  Human-readable explanation.

Example:

```json
{
  "status": "error",
  "code": "string",
  "description": "string"
}
```

### 401

Authentication required (`ERR_AUTHENTICATION_REQUIRED`).

- `status` ("error", required)
- `code` (string, required)
  Machine-readable error code (see specs/errors.md).
- `description` (string, required)
  Human-readable explanation.

Example:

```json
{
  "status": "error",
  "code": "string",
  "description": "string"
}
```

### 409

Device token is already registered to another identity.

- `status` ("error", required)
- `code` (string, required)
  Machine-readable error code (see specs/errors.md).
- `description` (string, required)
  Human-readable explanation.

Example:

```json
{
  "status": "error",
  "code": "string",
  "description": "string"
}
```

### 500

Internal server error (`ERR_DATABASE_ERROR`, `ERR_INTERNAL`).

- `status` ("error", required)
- `code` (string, required)
  Machine-readable error code (see specs/errors.md).
- `description` (string, required)
  Human-readable explanation.

Example:

```json
{
  "status": "error",
  "code": "string",
  "description": "string"
}
```