Physical POS
API Reference
Device Identity

Device Identity

Who calls these endpoints?External API (s2s)
Base path
/api/v1/physical-pos
Identity
Ed25519 request signature on every request — X-Key-Id, X-Date, X-Nonce, X-Signature, plus Digest on 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 gets 403 PRODUCT_NOT_ENABLED; without the scope 403 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.

MethodPathScope
POST/api/v1/physical-pos/devices/{deviceId}/activation-codephysical_pos:identity
POST/api/v1/physical-pos/devices/{deviceId}/activation-code/revokephysical_pos:identity
GET/api/v1/physical-pos/devices/{deviceId}/keysphysical_pos:view
POST/api/v1/physical-pos/devices/{deviceId}/keys/{keyId}/revokephysical_pos:identity
POST/api/v1/physical-pos/devices/{deviceId}/keys/{keyId}/revert-enrollmentphysical_pos:identity
  • The physical_pos:identity scope 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 get 409 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_activated is recorded.

Device identity in the panel

ScreenWhereWhat you do
Add device with codePhysical POS › Devices › Add device with codeYou 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 tabDevices › device detail › IdentityEnter 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

FieldTypeDescription
keyIdstringThe key's ID: 28 characters starting with pdk_.
algorithmstringED25519 or P256.
keyAlgorithmstring | nullThe key profile, in lower case: ed25519 or p256.
keyStatusstringACTIVE: 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.
enrolledViastringHow the key was obtained: PAIRING, ACTIVATION_CODE or ROTATION (a key that replaced the previous one).
fingerprintstringThe 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.
lineageRootKeyIdstringThe first key of the key lineage. Key rotations continue the same lineage; on the lineage's first key it is its own keyId.
rotatedFromKeyIdstring | nullOn a ROTATION key, the key it replaced; otherwise null.
activatedAtstringWhen the key became active.
supersededAtstring | nullWhen it was replaced by a newer key.
revokedAtstring | nullWhen it was revoked.
revokeReasonstring | nullWhy it was revoked: the reasonCode you sent, or PAIRING_REVERTED if the enrollment was reverted.
rowVersionintegerThe record's version; you send it when revoking the key.
lineageRootPairingIdstring | nullIf 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.

FieldTypeRequiredDescription
reasonCodestringYesMERCHANT_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.

FieldTypeRequiredDescription
rowVersionintegerYesThe key's rowVersion as read from the list.
reasonCodestringYesDEVICE_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) gets 409 physical_pos.device.key_not_active.
  • If rowVersion is 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:

lineageRootPairingIdHow 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.

FieldTypeRequiredDescription
reasonCodestringYesNOT_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's lineageRootPairingId points 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

HTTPcodeWhen
400VALIDATION_ERRORUndefined body field; rowVersion is not a JSON integer.
400physical_pos.input.reason_code_invalidreasonCode is not on the list or does not fit the operation.
400physical_pos.input.environment_invalidenvironment in the request.
400physical_pos.cursor.invalidBroken cursor on the key list.
403physical_pos.environment.test_key_read_onlyWrite request made with a test key.
403physical_pos.device.api_activation_code_disabledIssuing activation codes with an API key is currently disabled.
404physical_pos.device.not_foundThe device does not exist, is not yours or is in the other environment.
404physical_pos.device.key_not_foundThe key does not belong to this device or does not exist.
409physical_pos.device.activation_code_not_openNo open activation code to revoke.
409physical_pos.device.key_not_activeThe key was replaced by a newer one; it cannot be revoked.
409physical_pos.device.enrollment_not_revertibleThe enrollment was not made with an activation code, or no active key is left in the lineage.
409physical_pos.device_key.invalid_transitionThe key's status does not allow this operation.
409physical_pos.device.retiredRetired device.
409physical_pos.version_conflictrowVersion is not current.
429RATE_LIMITEDDevice identity write limit exceeded. → Rate limits
503physical_pos.service.busyThe record is busy with another operation; retry the same request.

All codes: Error Codes.