# Enroll a Device

Before a device can receive payment sessions, it must be enrolled on your merchant account. Your backend (or the Kustom Portal) generates a pairing code that a store clerk enters in the Kustom POS app. This registers the device automatically and receives an authentication token.

## Participants

| Participant | Role |
|  --- | --- |
| **Merchant Ops** | Merchant internal team with access to the Kustom Portal — or a third-party system connected to the Kustom Device API. Creates enrollments and controls which devices are assigned to specific locations. |
| **Store Clerk** | Merchant employee using the Kustom POS app to collect in-person payments; enters the pairing code in the app. |
| **Kustom POS** | Kustom POS app for iOS or Android running on any certified device. |
| **Device API** | Kustom device API, used to manage the device fleet. |


## How enrollment works

The first step (creating the enrollment) is the only part you implement, and it uses your API key. Registering the device is handled internally by the Kustom POS app once the clerk enters the pairing code.


```mermaid
sequenceDiagram
	actor Merchant Ops
	actor Shopper
	actor Store Clerk
	participant Kustom POS
	participant Device API
	
	critical Authentication using API keys
		Merchant Ops->>+Device API: Create enrollment
	  Note over Merchant Ops,Device API: Merchant operations create enrollment via portal or API.<br>The enrollment has an expiration date and metadata (key-value)<br>that will be carried over to the device record once pairing code is linked to the device<br>and could be used to query devices.
	  Device API->>-Merchant Ops: Return pairing code
  end

  critical No authentication
	  Merchant Ops->>Store Clerk: Sends pairing code
	  Note over Merchant Ops,Store Clerk: Merchants decide how to distribute the pairing code.
	  Store Clerk->>Kustom POS: Enter pairing code
	
	  Kustom POS->>+Device API: Register device
		Note over Kustom POS,Device API: Use pairing code to register device<br>and connect it to merchant
		Device API->>-Kustom POS: Return device record and auth credentials
		Note over Kustom POS,Device API: Credentials returned at this point will<br>be used for further API requests from Kustom POS
	end
```

## Create an enrollment

Generates a short-lived pairing code. The metadata you provide in the enrollment is carried over to the device record once paired, and can be used later to filter devices.

#### Generate an enrollment code

Share the `enrollment_code` with the store clerk, and they will enter it in the Kustom POS app. The app then calls the device registration endpoint (unauthenticated) and receives a device bearer token. This is handled entirely by the app; no further action is needed from your backend.

### Enrollment status

| Status | Meaning |
|  --- | --- |
| `PENDING` | Code generated, not yet entered by a clerk. |
| `CONSUMED` | Device successfully registered. |
| `EXPIRED` | Code not used before `expires_at`. Please generate a new enrollment. |
| `CANCELLED` | Manually deleted via `DELETE /ipp/v1/enrollments/{id}`. |


`CANCELLED` and `EXPIRED` enrollments are excluded from the list results. If the code expires before the clerk enters it, create a new enrollment.

## Manage registered devices

Once enrolled, a device has a stable `device_id`, which you use when creating sessions. The device metadata (carried over from the enrollment) can be used to filter devices in list queries.

#### List devices

#### Update device

#### Deregister a device

Deregistering a device revokes its bearer token immediately. The clerk will need to re-enroll if the device is to be used again.