Ga naar inhoud
buildinglinksbuildinglinks

Start `bl login` (device authorization)

POST
/api/v1/cli/device
curl --request POST \
  --url https://example.com/api/v1/cli/device \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'DPoP: example' \
  --data client_id=example \
  --data device_name=example \
  --data client_version=example

RFC 8628 §3.1 with client_id=bl, and a DPoP proof (RFC 9449) that binds the device code to the key of bl: only that key gets the tokens. A user approves at verification_uri_complete: after a login at the identity provider, on an explicit confirmation page. At most 30 device codes per minute for the service. Only a service that offers bl login (the connector, not the authority).

Authorizations

Section titled “Authorizations”
  • None

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
DPoP
required
string

A DPoP proof for this request.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/x-www-form-urlencoded
object
client_id
required

Always bl.

string
device_name

The name of the machine, shown to the user who approves.

string | null
client_version

The version of bl, shown to the user who approves.

string | null

Example generated

client_id=example&device_name=example&client_version=example

Responses

Section titled “Responses”

200

Section titled “200”

OK.

Media typeapplication/json

RFC 8628 §3.2.

object
device_code
required
string
user_code
required

Eight consonants, for the user to compare.

string
verification_uri
required
string
verification_uri_complete
required
string
expires_in
required

Seconds.

integer format: int64
interval
required

Seconds between polls of the token endpoint.

integer format: int64

Example generated

{
  "device_code": "example",
  "user_code": "example",
  "verification_uri": "example",
  "verification_uri_complete": "example",
  "expires_in": 1,
  "interval": 1
}

400

Section titled “400”

invalid_request, invalid_dpop_proof.

Media typeapplication/json

An OAuth 2.0 error (RFC 6749 §5.2).

object
error
required
string
error_description
required
string

Example 

{
  "error": "invalid_request"
}

401

Section titled “401”

invalid_client: the client is not bl.

Media typeapplication/json

An OAuth 2.0 error (RFC 6749 §5.2).

object
error
required
string
error_description
required
string

Example 

{
  "error": "invalid_request"
}

429

Section titled “429”

slow_down: too many login requests.

Media typeapplication/json

An OAuth 2.0 error (RFC 6749 §5.2).

object
error
required
string
error_description
required
string

Example 

{
  "error": "invalid_request"
}