Device Authorization

Most hasp login flows use a browser redirect with a local loopback listener (see OAuth Quickstart). That doesn’t work over SSH, in a container, or on a machine with no browser. The device authorization grant (RFC 8628) is the fallback: the CLI displays a short code, you enter it on any other device with a browser, and the CLI polls for completion. This is a hasp CLI concern, not something most API integrators need to implement directly — it’s documented here because the two endpoints it uses are part of the public /v1 OAuth surface.

Flow overview

The CLI (auto-detecting no browser/loopback available) requests a device code.
It shows you a short user_code and a URL to visit.
You open the URL on any device, sign in, and approve.
Meanwhile the CLI polls the token endpoint until you approve (or the code expires).

1. Request a device code

POST /v1/oauth/device_authorization

Stateless, unauthenticated (the device_code itself becomes the proof of possession). Rate-limited (60 requests/minute) since it’s public and DB-writing.

curl -X POST https://api.usehasp.com/v1/oauth/device_authorization \
  -d "client_id=hasp-cli" \
  -d "scope=hasp.data.read hasp.data.write"

{
  "device_code": "e6cf...redacted",
  "user_code": "WXYZ-ABCD",
  "verification_uri": "https://app.usehasp.com/v1/oauth/device",
  "verification_uri_complete": "https://app.usehasp.com/v1/oauth/device?user_code=WXYZ-ABCD",
  "expires_in": 900,
  "interval": 5
}

Field	Meaning
`device_code`	Opaque, long-lived poll token. Never displayed to the user — only used by the polling client.
`user_code`	Short, human-enterable code shown to the user.
`verification_uri`	Where the user enters `user_code` manually.
`verification_uri_complete`	Same page, pre-filled — use this for a QR code or clickable link.
`expires_in`	Seconds until the device code expires (900s / 15 minutes).
`interval`	Minimum seconds to wait between polls (see Polling below).

An unknown or inactive client_id returns a 400 with the standard RFC 6749 shape: {"error": "invalid_client", "error_description": "..."}.

2. User approves

Direct the user to verification_uri_complete (or verification_uri + manually entering user_code). This is a normal authenticated, session-based HASP page — the user signs in if needed, sees the code, and approves or denies.

3. Poll the token endpoint

POST /v1/oauth/token
grant_type=urn:ietf:params:oauth:grant-type:device_code

curl -X POST https://api.usehasp.com/v1/oauth/token \
  -d "grant_type=urn:ietf:params:oauth:grant-type:device_code" \
  -d "device_code=e6cf...redacted" \
  -d "client_id=hasp-cli"

Poll no more often than every interval seconds (the value returned in step 1). While the user hasn’t approved yet, every poll returns:

{ "error": "authorization_pending", "error_description": "The user has not yet completed authorization." }

Once approved, the same poll returns a normal token response:

{
  "access_token": "hasp_pat_live_...",
  "token_type": "Bearer",
  "scope": "hasp.data.read hasp.data.write"
}

Polling error codes (RFC 8628 §3.5)

`error`	Meaning	What to do
`authorization_pending`	Still waiting on the user.	Keep polling at `interval`.
`slow_down`	Polling too frequently.	Increase your polling interval by 5 seconds and continue.
`access_denied`	The user denied the request.	Stop polling. Restart the flow if the user wants to retry.
`expired_token`	The device code’s 15-minute window elapsed before approval.	Stop polling. Request a new device code (step 1).
`invalid_grant`	Unknown device code, or it was already exchanged for a token.	Stop polling. A device code is single-use.

Security notes

user_code is short and human-facing by design (RFC 8628’s threat model accepts this given the 15-minute expiry and the fact that guessing it grants nothing without also completing an authenticated approval step).
device_code is long, unguessable, and never displayed — only ever transmitted machine-to-machine between the CLI and the token endpoint.
A device code is single-use: once exchanged for a token (or denied), polling it again returns invalid_grant.

AI Studio

Platform

AI API

App Builder SDK

Device Authorization

Flow overview

1. Request a device code

2. User approves

3. Poll the token endpoint

Polling error codes (RFC 8628 §3.5)

Security notes

​Flow overview

​1. Request a device code

​2. User approves

​3. Poll the token endpoint

​Polling error codes (RFC 8628 §3.5)

​Security notes

Flow overview

1. Request a device code

2. User approves

3. Poll the token endpoint

Polling error codes (RFC 8628 §3.5)

Security notes