Apps

Request a device code

Returns a device code and a user code (RFC 8628). Show the person verification_uri and user_code, then poll POST /oauth/token with the device code until they approve or deny it.

POST
/oauth/device-authorization

Request body

application/x-www-form-urlencoded
  1. body
client_id*string

The client ID from POST /oauth/register.

scope?string

Space-separated scopes to ask for. Defaults to the scopes the app registered for.

max_age?string

Seconds since the owner last signed in that the approval accepts. An older browser session is asked to sign in again before it approves. 0 asks for a sign-in after this request.

Match^[0-9]+$

Response body

About errors

Returns the device code, the user code and where the person approves it.

application/json
  1. response
device_code*string

The code you poll POST /oauth/token with. Keep it secret.

user_code*string

The code the person types on the approval page.

verification_uri*string

The page where the person types the user code.

Formaturi
verification_uri_complete*string

The same page with the user code filled in.

Formaturi
expires_in*integer

Seconds until the device code expires.

interval*integer

Seconds to wait between polls.

An error in the shape RFC 8628 defines:

  • invalid_request: client_id is missing.
  • invalid_scope: no scope asked for can be granted.
  • unauthorized_client: the client isn't registered for the device grant.
application/json
  1. response
error*string

The OAuth error code.

Value in"invalid_request""invalid_scope""unauthorized_client"
error_description?string

A description of the error for a person to read.

An error in the shape RFC 6749 defines:

  • invalid_client: the client_id names no client, or the request authenticates the client, which a public client doesn't.
application/json
  1. response

An OAuth error in the shape RFC 6749 defines, for a client Marfa does not accept.

error*"invalid_client"

The OAuth error code.

Value in"invalid_client"
error_description?string

A description of the error for a person to read.

request_timeout: the request body didn't arrive whole within 180 seconds. Nothing changed, and Marfa closed the connection. Send the request again. A body larger than about 21 MiB can't arrive in that time over a 1 Mbit/s link, so send it in smaller requests.

application/json
  1. response

An error response.

error*

What went wrong.

contract_mismatch: X-Marfa-Contract names another contract version than this instance speaks, or is not a whole number. Nothing was done.

application/json
  1. response

An error response.

error*

What went wrong.

request_too_large: the request body is larger than this instance accepts.

application/json
  1. response

An error response.

error*

What went wrong.

rate_limited: you sent too many requests. Wait for the number of seconds in Retry-After, then try again.

application/json
  1. response

An error response.

error*

What went wrong.

internal_error: Marfa failed in a way it didn't expect, and the request may not have completed. Read what you changed before you repeat a write.

application/json
  1. response

An error response.

error*

What went wrong.

write_contention: the database was busy, and Marfa couldn't complete the request in time. Nothing changed. Try the request again. While a restore runs, details.reason is restore_running.

application/json
  1. response

An error response.

error*

What went wrong.

curl -X POST 'http://localhost:8600/oauth/device-authorization' \  -H 'Content-Type: application/x-www-form-urlencoded' \  -d 'client_id=string'
About errors
{  "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",  "user_code": "BCDFGHJK",  "verification_uri": "https://marfa.example/auth/device",  "verification_uri_complete": "https://marfa.example/auth/device?user_code=BCDFGHJK",  "expires_in": 600,  "interval": 5}