Device Authorization

Start the OAuth 2.0 device flow. This is how a terminal client authenticates a human without handling their credentials.

POST https://api.noorle.com/oauth/device/authorize
Content-Type: application/json

Request

curl -X POST https://api.noorle.com/oauth/device/authorize \
  -H "Content-Type: application/json" \
  -d '{"client_id": "noorle-cli"}'

Field	Type	Required	Description
`client_id`	string	Yes	OAuth client identifier. The Noorle CLI uses `noorle-cli`
`scope`	string	No	Requested scope

Response

Returned bare — unlike the /v1 endpoints, it is not wrapped in a data envelope.

{
  "device_code": "dc_k3Jd82nfPqW0zXbA7yTvR5mLcH1sGe4U",
  "user_code": "KHJM-7RQP",
  "verification_uri": "https://<portal-host>/oauth/device/verify",
  "verification_uri_complete": "https://<portal-host>/oauth/device/verify?user_code=KHJM-7RQP",
  "expires_in": 900,
  "interval": 5
}

Field	Type	Description
`device_code`	string	Opaque code, `dc_` followed by 32 alphanumerics. Send this back to `/oauth/token`
`user_code`	string	Eight characters, formatted `XXXX-XXXX`, for the human to type
`verification_uri`	string	Where the human approves — the device-verify page in the Portal
`verification_uri_complete`	string	The same URL with `user_code` prefilled
`expires_in`	integer	900 — the lifetime advertised for the device code, in seconds
`interval`	integer	5 seconds — the minimum poll interval

verification_uri is served by the Portal, not by the management API, and its host is built from the environment the API runs in. Show the human the value that came back in the response — do not hard-code a host.

Flow

Request a device code. The response carries both codes, the verification URL, and the poll interval.
Show the human verification_uri and user_code. Or open verification_uri_complete directly.
Poll /oauth/token every interval seconds until it returns a token or a terminal answer.

Polling

Poll no faster than interval — 5 seconds. A 400 means the human has not decided; keep waiting. Stop on a 200 (you have a token) or a 403 (the human declined), and bound the number of attempts. Branch on the status code rather than on the contents of the error body. Once a device code stops being usable, the answer is terminal: request a new device code and start over rather than continuing to poll the old one.

On approval, the exchange consumes the session — the device code is single-use. A second poll after a successful exchange finds no session.

Status codes

Code	Meaning
200	Codes issued
400	Malformed request body

There is no rate limit on this endpoint.

Get Token — the polling step
Authentication

Overview

REST API

MCP Protocol

A2A Protocol

Noorle CLI

Device Authorization

Request

Response

Flow

Polling

Status codes

​Request

​Response

​Flow

​Polling

​Status codes

​Related

Request

Response

Flow

Polling

Status codes

Related