Device Identity
- Base path
/api/v1/physical-pos- Identity
- Ed25519 request signature on every request —
X-Key-Id,X-Date,X-Nonce,X-Signature, plusDigeston requests with a body. ±5 min clock window, single-use nonce. A Bearer token or a panel session is not accepted here. - Authorization
- The key must carry the Physical POS product (
PHYSICAL_POS) and the scope for the endpoints on this page:physical_pos:view·physical_pos:identity. Without the product the call gets403 PRODUCT_NOT_ENABLED; without the scope403 API_INSUFFICIENT_SCOPE. See Authentication and Scopes. - Cross-surface
- These endpoints are the s2s surface — call them from your own server with a signed request. The same records have screens in the panel, but panel endpoints cannot be called with an API key, and these endpoints cannot be called with a panel session.
Every physical POS device connects to Lunixi with its own identity key. The key is generated on the device and never leaves it; Lunixi stores only the public key and its fingerprint.
You connect a device by pairing it: the Lunixi app on the device shows a pairing code on its screen; you enter the code in the panel and confirm it with the last 4 digits of the device's serial number. The paired device receives its key, its ownership is verified and, if it is PENDING, it becomes ACTIVE. The activation code is a fallback path; it is issued in the panel, and issuing it from the API is currently disabled. → Device identity in the panel
With the endpoints on this page you view and revoke a device's identity keys, manage activation codes and revert an enrollment made with an activation code.
| Method | Path | Scope |
|---|---|---|
POST | /api/v1/physical-pos/devices/{deviceId}/activation-code | physical_pos:identity |
POST | /api/v1/physical-pos/devices/{deviceId}/activation-code/revoke | physical_pos:identity |
GET | /api/v1/physical-pos/devices/{deviceId}/keys | physical_pos:view |
POST | /api/v1/physical-pos/devices/{deviceId}/keys/{keyId}/revoke | physical_pos:identity |
POST | /api/v1/physical-pos/devices/{deviceId}/keys/{keyId}/revert-enrollment | physical_pos:identity |
- The
physical_pos:identityscope is not added to your key automatically; select it explicitly on the key that will use these endpoints. → Scopes - A test key can only read the key list; write requests get
403 physical_pos.environment.test_key_read_only. → Environments - A device of another organization or of the other environment gets the same answer as a device that does not exist:
404 physical_pos.device.not_found. Write requests on a retired device get409 physical_pos.device.retired. - Write requests are rate limited: per 60 seconds, 10 requests per API key and 30 per organization. The organization counter is shared with the same operations in the panel. → Rate limits
- Every write is recorded in the device's change history:
physical_pos.audit.device_activation_code_issued,…device_activation_code_revoked,…device_key_revoked,…device_enrollment_reverted. When a device receives a key,…device_key_activatedis recorded.
Device identity in the panel
| Screen | Where | What you do |
|---|---|---|
| Add device with code | Physical POS › Devices › Add device with code | You enter the pairing code from the device screen. You compare the vendor, model, serial number and key fingerprint the device reports with the device itself and approve by typing the last 4 digits of the serial number. The device is paired with a new record or with its existing record. |
| Identity tab | Devices › device detail › Identity | Enter a pairing code for this device, issue and revoke a fallback activation code, view and revoke keys, revert an enrollment. |
| Pairing detail | /physical-pos/pairings/{pairingId} | The pairing's details and revert. The link in the "new device paired" security notification opens this page. |
Identity operations require the device identity management permission (physical_pos:identity) on your panel user; a user without it can only view keys.
The cURL examples compute the signature with lunixi-sign.sh: Authentication › Signing helper.
Key object
| Field | Type | Description |
|---|---|---|
keyId | string | The key's ID: 28 characters starting with pdk_. |
algorithm | string | ED25519 or P256. |
keyAlgorithm | string | null | The key profile, in lower case: ed25519 or p256. |
keyStatus | string | ACTIVE: the device connects with this key. SUPERSEDED: replaced by a newer key during key rotation. REVOKED: revoked. A device has at most one ACTIVE key at a time. |
enrolledVia | string | How the key was obtained: PAIRING, ACTIVATION_CODE or ROTATION (a key that replaced the previous one). |
fingerprint | string | The public key's short fingerprint, formatted XXXX-XXXX (the first 8 hex digits of its SHA-256 digest). You see the same value on the device screen and in the panel. The key itself is never in any response. |
lineageRootKeyId | string | The first key of the key lineage. Key rotations continue the same lineage; on the lineage's first key it is its own keyId. |
rotatedFromKeyId | string | null | On a ROTATION key, the key it replaced; otherwise null. |
activatedAt | string | When the key became active. |
supersededAt | string | null | When it was replaced by a newer key. |
revokedAt | string | null | When it was revoked. |
revokeReason | string | null | Why it was revoked: the reasonCode you sent, or PAIRING_REVERTED if the enrollment was reverted. |
rowVersion | integer | The record's version; you send it when revoking the key. |
lineageRootPairingId | string | null | If the lineage started with pairing, the ID of that pairing; null if it started with an activation code. This field decides how the enrollment is reverted. → Revert an enrollment |
Issue an activation code
POST /api/v1/physical-pos/devices/{deviceId}/activation-code
Issuing activation codes with an API key is currently disabled. The request gets 403 physical_pos.device.api_activation_code_disabled. Connect the device by pairing it.
Revoke an activation code
POST /api/v1/physical-pos/devices/{deviceId}/activation-code/revoke
Revokes the device's open (unused and unexpired) activation code. The device cannot connect with a revoked code.
| Field | Type | Required | Description |
|---|---|---|---|
reasonCode | string | Yes | MERCHANT_REVOKED, DEVICE_LOST, DEVICE_STOLEN or OTHER. |
source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/devices/00000000-0000-0000-0000-000000000401/activation-code/revoke"
BODY='{"reasonCode":"MERCHANT_REVOKED"}'
lunixi_sign POST "$REQ_PATH" "$BODY"
curl -X POST "https://api-gateway.lunixi.com$REQ_PATH" \
-H "Content-Type: application/json" \
-H "X-Key-Id: $LUNIXI_KEY_ID" \
-H "X-Date: $DATE" \
-H "X-Nonce: $NONCE" \
-H "Digest: $DIGEST" \
-H "X-Signature: $SIGNATURE" \
--data-raw "$BODY"The response (200) returns { "deviceId": "…", "revokedAt": "…", "revokeReason": "MERCHANT_REVOKED" } in data. If the device has no open code: 409 physical_pos.device.activation_code_not_open.
List keys
GET /api/v1/physical-pos/devices/{deviceId}/keys · physical_pos:view
Lists all of the device's identity keys (active, superseded and revoked), newest first. Takes limit (1–100, default 25) and cursor. The response is { "items": [ … ], "pageInfo": { … } }; each item is a key object.
source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/devices/00000000-0000-0000-0000-000000000401/keys?limit=25"
lunixi_sign GET "$REQ_PATH"
curl "https://api-gateway.lunixi.com$REQ_PATH" \
-H "X-Key-Id: $LUNIXI_KEY_ID" \
-H "X-Date: $DATE" \
-H "X-Nonce: $NONCE" \
-H "X-Signature: $SIGNATURE"{
"items": [
{
"keyId": "pdk_AAAAAAAAAAAAAAAAAAAAAAAA",
"algorithm": "ED25519",
"keyStatus": "ACTIVE",
"enrolledVia": "PAIRING",
"fingerprint": "3F2A-91C4",
"lineageRootKeyId": "pdk_AAAAAAAAAAAAAAAAAAAAAAAA",
"rotatedFromKeyId": null,
"activatedAt": "2026-01-02T09:00:00.000Z",
"supersededAt": null,
"revokedAt": null,
"revokeReason": null,
"rowVersion": 1,
"lineageRootPairingId": "01900000-0000-7000-8000-000000000701"
}
],
"pageInfo": { "hasMore": false, "nextCursor": null, "totalCount": null }
}Revoke a key
POST /api/v1/physical-pos/devices/{deviceId}/keys/{keyId}/revoke
Revokes the device's active key. Use it for a lost or stolen device, or one you suspect is compromised. After revocation the device is disconnected from Lunixi and cannot reconnect with this key; to use the device again you must pair it again.
| Field | Type | Required | Description |
|---|---|---|---|
rowVersion | integer | Yes | The key's rowVersion as read from the list. |
reasonCode | string | Yes | DEVICE_LOST, DEVICE_STOLEN, KEY_COMPROMISED, DEVICE_REPLACED, MERCHANT_REQUEST or OTHER. |
source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/devices/00000000-0000-0000-0000-000000000401/keys/pdk_AAAAAAAAAAAAAAAAAAAAAAAA/revoke"
BODY='{"rowVersion":1,"reasonCode":"DEVICE_STOLEN"}'
lunixi_sign POST "$REQ_PATH" "$BODY"
curl -X POST "https://api-gateway.lunixi.com$REQ_PATH" \
-H "Content-Type: application/json" \
-H "X-Key-Id: $LUNIXI_KEY_ID" \
-H "X-Date: $DATE" \
-H "X-Nonce: $NONCE" \
-H "Digest: $DIGEST" \
-H "X-Signature: $SIGNATURE" \
--data-raw "$BODY"Response (200): { "key": { … }, "lifecycleStatus": "ACTIVE", "replayed": false }. key is the revoked key (keyStatus: "REVOKED"); lifecycleStatus is the device's current lifecycle status.
- On a key that is already revoked, the request returns the same result with
replayed: true; nothing is written again. - A key that was replaced by a newer one (
SUPERSEDED) gets409 physical_pos.device.key_not_active. - If
rowVersionis not current:409 physical_pos.version_conflict.
Revoking a key does not change the device's lifecycle. To also stop the device from taking payments, suspend it.
Revert an enrollment
POST /api/v1/physical-pos/devices/{deviceId}/keys/{keyId}/revert-enrollment
Reverts an enrollment made with an activation code. Use it if you did not connect the device yourself or the wrong device was connected.
The key's lineageRootPairingId field decides which path to use:
lineageRootPairingId | How to revert |
|---|---|
null (connected with an activation code) | With this endpoint or from the device's Identity tab in the panel. |
| Set (connected by pairing) | Only in the panel: the device's Identity tab or the pairing detail page /physical-pos/pairings/{lineageRootPairingId}. There is no API endpoint for this. |
Reverting a pairing has the same effects as below, with one difference: if the device record was created during pairing, the device is retired (RETIRED) instead of suspended.
| Field | Type | Required | Description |
|---|---|---|---|
reasonCode | string | Yes | NOT_MY_DEVICE, SUSPECTED_PHISHING, WRONG_DEVICE or OTHER. |
You can pass any key of the lineage as keyId; the operation covers the whole lineage. In the same operation:
- The lineage's active key is revoked (
revokeReason: "PAIRING_REVERTED") and the device is disconnected. - The device becomes
SUSPENDED; its ownership verification is kept. - The verification of logical terminals verified through this enrollment is withdrawn. If a terminal has no other verification, it becomes
ownershipStatus: "UNVERIFIED"and cannot take payments. - A "device pairing reverted" security notification is sent.
source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/devices/00000000-0000-0000-0000-000000000401/keys/pdk_BBBBBBBBBBBBBBBBBBBBBBBB/revert-enrollment"
BODY='{"reasonCode":"NOT_MY_DEVICE"}'
lunixi_sign POST "$REQ_PATH" "$BODY"
curl -X POST "https://api-gateway.lunixi.com$REQ_PATH" \
-H "Content-Type: application/json" \
-H "X-Key-Id: $LUNIXI_KEY_ID" \
-H "X-Date: $DATE" \
-H "X-Nonce: $NONCE" \
-H "Digest: $DIGEST" \
-H "X-Signature: $SIGNATURE" \
--data-raw "$BODY"Response (200): { "key": { … }, "lifecycleStatus": "SUSPENDED", "replayed": false }.
- A key whose lineage started with pairing (root
enrolledVia: "PAIRING") cannot be reverted with this endpoint:409 physical_pos.device.enrollment_not_revertible. Revert the pairing in the panel: the key'slineageRootPairingIdpoints to the pairing detail page. - If no active key is left in the lineage, you also get
409 physical_pos.device.enrollment_not_revertible; use key revocation or retirement instead. - There is no time limit on reverting.
Errors
| HTTP | code | When |
|---|---|---|
400 | VALIDATION_ERROR | Undefined body field; rowVersion is not a JSON integer. |
400 | physical_pos.input.reason_code_invalid | reasonCode is not on the list or does not fit the operation. |
400 | physical_pos.input.environment_invalid | environment in the request. |
400 | physical_pos.cursor.invalid | Broken cursor on the key list. |
403 | physical_pos.environment.test_key_read_only | Write request made with a test key. |
403 | physical_pos.device.api_activation_code_disabled | Issuing activation codes with an API key is currently disabled. |
404 | physical_pos.device.not_found | The device does not exist, is not yours or is in the other environment. |
404 | physical_pos.device.key_not_found | The key does not belong to this device or does not exist. |
409 | physical_pos.device.activation_code_not_open | No open activation code to revoke. |
409 | physical_pos.device.key_not_active | The key was replaced by a newer one; it cannot be revoked. |
409 | physical_pos.device.enrollment_not_revertible | The enrollment was not made with an activation code, or no active key is left in the lineage. |
409 | physical_pos.device_key.invalid_transition | The key's status does not allow this operation. |
409 | physical_pos.device.retired | Retired device. |
409 | physical_pos.version_conflict | rowVersion is not current. |
429 | RATE_LIMITED | Device identity write limit exceeded. → Rate limits |
503 | physical_pos.service.busy | The record is busy with another operation; retry the same request. |
All codes: Error Codes.