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": 600,
  "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	600 — 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.

Branch on the error field in the body, not on the status code. Five different outcomes all return HTTP 400, and only two of them mean “keep waiting”. A loop that treats 400 as “still pending” never terminates on a declined or expired code.

`error`	HTTP	What it means
— (200)	200	You have a token. Stop.
`authorization_pending`	400	The human has not decided yet. Keep polling.
`slow_down`	400	You are polling too fast. Back off, then keep polling.
`access_denied`	400	The human declined. Terminal.
`expired_token`	400	The device code expired. Terminal.
`invalid_grant`	400	Unknown or already-redeemed code. Terminal.
`server_error`	500	Retry the poll.

Note that a decline is access_denied on HTTP 400, not a 403. 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. Bound the number of attempts regardless.

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	Rejected through the device-flow error carrier (an `error` field, as in the polling table above)
422	Request body failed validation — the standard management-API error shape, `category: "Validation"`

A rejected body comes back as 422, not 400: validation failures travel the normal management-API carrier, where Validation maps to 422. The 400s on this endpoint family are the RFC 8628 device-flow errors. 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