Device Tokens

A device token lets an external backend verify the identity of a connected device. Nexigon Hub issues the token through Nexigon Agent and validates it through the Actions API. Validation returns the device ID and any custom claims.

Device tokens are for integrations with external systems. They do not replace the credentials used to connect a device.

Identity Exchange

An application running on a device requests a token from Nexigon Agent and sends it to its own backend. The backend asks Nexigon Hub to validate the token before associating the returned device ID with an account.

The backend can store that device ID to retain the association after the short-lived token expires. The token proves identity during the exchange; the stored association belongs to your application. Deleting and re-enrolling a device creates a new Nexigon device ID, so account-linking workflows must handle that change. See Device Deletion and Re-enrollment.

sequenceDiagram
    participant App as Device Application
    participant Agent as Nexigon Agent
    participant Backend as Application Backend
    participant Hub as Nexigon Hub
    App->>Agent: Request device token
    Agent->>Hub: Issue device token
    Hub->>Agent: Token
    Agent->>App: Token
    App->>Backend: Token
    Backend->>Hub: Validate token
    Hub->>Backend: Device ID and claims
    Backend->>App: Association confirmed

The application must also authenticate its user to its own backend. A valid device token proves device identity, not ownership of an application account.

Issue a Token

Run this on the device:

nexigon-agent device tokens issue \
  --valid-for 600 \
  --claims '{"purpose": "com.example.account-link"}'

The command returns a JSON object containing jwt, for example:

{ "jwt": "<device-token>" }

Send that field’s string value to your backend, which validates it in the next step.

--valid-for sets validity in seconds. The default is 600 seconds (10 minutes). --claims attaches an arbitrary JSON value.

Use a purpose-specific claim and check it during validation so that a token issued for one integration cannot be accepted for another purpose.

Validate a Token

The backend invokes devices_ValidateDeviceToken with the issued token:

{ "jwt": "<device-token>" }

A valid result has this shape:

{
  "result": "Valid",
  "deviceId": "d_...",
  "claims": { "purpose": "com.example.account-link" }
}

An invalid token returns {"result": "Invalid"}. Before creating an association, require Valid and verify the expected claims. See Actions API for HTTP invocation and the HTTP API reference for the complete contract.