OAuth Device Flow

The device flow lets a command-line tool authenticate a human without handling their credentials and without running a local redirect server. The tool shows a code, the human approves it in a browser, the tool polls until a token appears.

This flow lives on the platform, at api.noorle.com, and the human-facing approval page is on the Portal. It is not served by the identity boundary at auth.noorle.com — the boundary advertises only the authorization-code grant. The two issue different tokens signed with different key material.

The shape

Step 1 — request a device code

POST https://api.noorle.com/oauth/device/authorize
{ "client_id": "your-client-id" }

The response carries:

Field	Value
`device_code`	`dc_` followed by 32 random alphanumerics. The secret half — keep it local.
`user_code`	Eight characters formatted `XXXX-XXXX`. What the human types.
`verification_uri`	The Portal’s device-verify page
`verification_uri_complete`	The same URL with the code pre-filled
`expires_in`	900 — fifteen minutes
`interval`	5 — poll no faster than every five seconds

The user-code alphabet excludes visually ambiguous characters, so a code read aloud or off a screen is unambiguous.

Step 2 — the human approves

Send them to verification_uri_complete if you can; otherwise print the plain URL and the code separately, because a code that has to be retyped is a code that gets typo’d.

To authorize, open:

  <verification_uri from the response>

and enter the code:

  ABCD-2345

Waiting…

Print the verification_uri the response gave you rather than a URL you hard-coded. The Portal host it points at is environment-specific, and the response is the authority on it.

Step 3 — poll for the token

POST https://api.noorle.com/oauth/token
{
  "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
  "code": "dc_…"
}

The device code goes in the code field, not a device_code field. That is the shape this endpoint accepts.

While waiting, the endpoint returns authorization_pending. Other outcomes: slow_down if you are polling too fast, access_denied if the human declined, and an expired-token error past fifteen minutes. On success:

{
  "access_token": "eyJ…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "eyJ…",
  "scope": "account:manage:{account_id}"
}

The session is cleaned up on success, so a device code is genuinely single-use.

What you get back

Access token. A JWT signed HS256, valid one hour. Send it as Authorization: Bearer …. Scope. account:manage:{account_id} — the scope identifies which account the token is good for. There is no read/write/admin scope split; authority comes from the approving user’s role and grants.

Plan for the hour. When an access token expires, run the device flow again — the human approves once more and you get a fresh token.

Using the token

curl https://api.noorle.com/v1/agents \
  -H "Authorization: Bearer $TOKEN"

The token’s issuer is stamped with the management-API host that served it, and validation checks that issuer. A token minted against one environment does not validate against another.

Storing it

The token is a bearer credential for one hour. Treat it accordingly:

A file with owner-only permissions, or the OS keychain.
Never a world-readable location, never a shell history, never a log line.
In a container, pass it as an environment variable rather than baking it into an image.

Security notes

The device code is the secret. Anyone holding it can poll for the token. It never goes on screen, never in a URL you display, never in a log. The user code is not a secret, but a wrong code is a code entered against someone else’s pending request. Fifteen minutes of validity bounds the exposure. Both codes are single-use. A successful exchange deletes the session.

Device flow or API key?

Use the device flow when a person is present and their identity should be on the record — the token carries their principal, so the audit trail names them. Use an API key when nobody is present. The device flow needs a human at a browser by construction, which an unattended job does not have.

Troubleshooting

Symptom	Cause
`authorization_pending` forever	The human never approved. Confirm they opened the page and entered the code.
`slow_down`	Polling faster than the returned `interval` of 5 seconds.
Expired after 15 minutes	The window elapsed. Start a new device authorization.
`access_denied`	The human declined.
`invalid_request`	Check that the device code is in the `code` field and the grant type string is exact.
401 after an hour	The access token expired. Start a new device authorization.

Next: JWT Tokens — what is actually inside these tokens, and which issuer signed them.

Getting Started

Core Concepts

Security & Auth

OAuth Device Flow

The shape

Step 1 — request a device code

Step 2 — the human approves

Step 3 — poll for the token

What you get back

Using the token

Storing it

Security notes

Device flow or API key?

Troubleshooting

​The shape

​Step 1 — request a device code

​Step 2 — the human approves

​Step 3 — poll for the token

​What you get back

​Using the token

​Storing it

​Security notes

​Device flow or API key?

​Troubleshooting

The shape

Step 1 — request a device code

Step 2 — the human approves

Step 3 — poll for the token

What you get back

Using the token

Storing it

Security notes

Device flow or API key?

Troubleshooting