# Devices & push

> Register handsets so pushes can address your user ids, and deactivate them on logout.

Pushes address your user ids, and Nofy resolves each id to handsets at
send time. That only works if your app registers its tokens. Registering
again is safe and expected: reinstalls and second-hand phones move tokens
between users, and registering moves the row instead of duplicating it.

## Register or refresh a handset

`POST /v2/devices`. No quota applies: registration is not a send.

```json
{
  "tenant": "company-uuid-1",
  "token": "fcm-device-token",
  "external_user_id": "user-uuid-1",
  "platform": "android"
}
```

It answers `201` (or `200` on a refresh) with a device id and a created
flag:

```json
{
  "device_id": "pU83nQx0aLr2",
  "created": true
}
```

`token` and `external_user_id` are required; `platform` is a short label.

!!! tip "Register on every app start"
    Registration moves the row instead of duplicating it, so calling it on
    every launch keeps Nofy's view of your users' handsets current.

## Remove handsets

`DELETE /v2/devices` deactivates and never deletes, so a returning token
matches its row instead of creating a duplicate. Deactivate one token, or
a user's whole fleet within a tenant:

### One handset
```json
{
  "token": "fcm-device-token"
}
```
### Everything a user has
```json
{
  "tenant": "company-uuid-1",
  "external_user_id": "user-uuid-1"
}
```

It answers with the number deactivated:

```json
{
  "deactivated": 2
}
```

## Token hygiene

Tokens that FCM reports permanently dead are deactivated at send time, so
reinstalls stop wasting a slot in every multicast. A user with no active
tokens fails that delivery permanently with a clear reason, which usually
means your app stopped registering.

### Register a device
Every field, with request and response examples.
### Deactivate devices
One token, or a user's whole fleet.