Integration guide

Connect a device.

Start device authorization with your tenant issuer, registered device client, API resources and granted scopes.

  1. Register a device application and grant it the scopes it needs for each target API. Use the tenant’s Identity origin as the issuer.
  2. Generate a fresh DPoP proof for the device-start POST using the installation key. Send client_id, one resource parameter per target API and scope to get the user code, verification URL, expiry and polling interval.
  3. Open the returned verification URL on another device. Sign in, review the device request, and approve or decline it.
  4. Poll /oauth2/token using grant_type=urn:ietf:params:oauth:grant-type:device_code, the issued device_code, client_id and one approved resource. Sign each poll with the same key and respect interval, authorization_pending, slow_down, expiry and denial.
device.sh
# Use your registered device client, API resource and scopes.
PLZI_ISSUER_URL=https://tenant.example.test
PLZI_CLIENT_ID=your-device-client-id
PLZI_RESOURCE=https://api.example.test/api/v1
scope='offline_access example:activate'

# Set device_proof to a fresh proof for this POST using the installation key.
curl --fail-with-body \
  "$PLZI_ISSUER_URL/oauth2/device/code" \
  --header "DPoP: ${device_proof:?Set a fresh device authorization proof}" \
  --data-urlencode "client_id=$PLZI_CLIENT_ID" \
  --data-urlencode "resource=$PLZI_RESOURCE" \
  --data-urlencode "scope=$scope"
Back to the interactive examples →