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.
application/x-www-form-urlencoded- body
client_id*stringThe client ID from POST /oauth/register.
scope?stringSpace-separated scopes to ask for. Defaults to the scopes the app registered for.
max_age?stringSeconds 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.
^[0-9]+$Returns the device code, the user code and where the person approves it.
application/json- response
device_code*stringThe code you poll POST /oauth/token with. Keep it secret.
user_code*stringThe code the person types on the approval page.
verification_uri*stringThe page where the person types the user code.
uriverification_uri_complete*stringThe same page with the user code filled in.
uriexpires_in*integerSeconds until the device code expires.
interval*integerSeconds to wait between polls.
An error in the shape RFC 8628 defines:
invalid_request:client_idis missing.invalid_scope: no scope asked for can be granted.unauthorized_client: the client isn't registered for the device grant.
application/json- response
error*stringThe OAuth error code.
"invalid_request""invalid_scope""unauthorized_client"error_description?stringA description of the error for a person to read.
An error in the shape RFC 6749 defines:
invalid_client: theclient_idnames no client, or the request authenticates the client, which a public client doesn't.
application/json- response
An OAuth error in the shape RFC 6749 defines, for a client Marfa does not accept.
error*"invalid_client"The OAuth error code.
"invalid_client"error_description?stringA 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- 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- response
An error response.
error*What went wrong.
request_too_large: the request body is larger than this instance accepts.
application/json- 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- 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- 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- 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'{ "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}