Device Authorization

OAuth 2.0 Device Authorization Grant (RFC 8628) for devices with limited input capabilities such as smart TVs, IoT devices, and CLI tools.

Activate Device

Start the device authorization flow. Returns a device code and user code for the end user to enter on a browser.

Endpoint: POST /uflow/activate

Request Body

{
  "client_id": "string"
}

Parameters

Parameter	Type	Required	Description
client_id	string	Yes	Client application identifier

Response

Success (200):

{
  "device_code": "string",
  "user_code": "string",
  "verification_uri": "string",
  "verification_uri_complete": "string",
  "expires_in": 600,
  "interval": 5
}

Response Fields

Field	Type	Description
device_code	string	Device code for polling
user_code	string	Code user enters on browser
verification_uri	string	URL where user enters the code
verification_uri_complete	string	URL with code pre-filled
expires_in	integer	Seconds until codes expire
interval	integer	Minimum polling interval in seconds

---

Complete Device Authorization

User authorizes the device by confirming the user code.

Endpoint: POST /uflow/auth/device/complete

Request Body

{
  "user_code": "string"
}

Headers

Header	Type	Required	Description
Authorization	string	Yes	Bearer JWT token

Response

Success (200):

{
  "message": "Device authorized successfully"
}

Error Responses:

• 400 - Bad request - invalid or expired code
• 401 - Unauthorized

---

Poll for Device Token

The device polls this endpoint until the user completes authorization.

Endpoint: POST /uflow/auth/device/token

Request Body

{
  "device_code": "string",
  "client_id": "string"
}

Response

Success (200):

{
  "access_token": "string",
  "refresh_token": "string",
  "token_type": "bearer",
  "expires_in": 3600
}

Pending (428):

{
  "error": "authorization_pending"
}

Error Responses:

• 400 - Bad request
• 403 - Expired or denied device code

Polling Flow

Device                    AuthSec                    User Browser
  |                         |                              |
  |-- POST /activate ------>|                              |
  |<--- device_code, -------|                              |
  |     user_code           |                              |
  |                         |                              |
  |                         |   User enters user_code      |
  |                         |<--- POST /auth/device/ ------|
  |                         |     complete                 |
  |                         |                              |
  |-- POST /auth/device/ -->|                              |
  |   token (poll)          |                              |
  |<--- access_token -------|                              |

---

Verify Device Code

Verify a device code before completion. Used by the browser-based verification page to display device details.

Endpoint: POST /uflow/auth/device/verify

Request Body

{
  "user_code": "string"
}

Response

Success (200):

{
  "client_id": "string",
  "status": "pending"
}

Error Responses:

• 400 - Bad Request
• 404 - User code not found or expired

---

Get Device Authorization Status

Retrieve the status of a device authorization request.

Endpoint: GET /uflow/auth/device/status

Query Parameters

Parameter	Type	Required	Description
device_code	string	Yes	The device code

Response

Success (200):

{
  "status": "pending | authorized | expired | denied",
  "client_id": "string"
}