Apps

Exchange a code for a token

Returns an access token for an authorization code, a refresh token or an approved device code (RFC 6749 and RFC 8628). A refresh token can be spent once: the answer carries the next one.

POST
/oauth/token

Request body

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

authorization_code, refresh_token, or urn:ietf:params:oauth:grant-type:device_code.

Value in"authorization_code""refresh_token""urn:ietf:params:oauth:grant-type:device_code"
client_id*string

The client ID the code or token was issued to.

code?string

The authorization code. Required for authorization_code.

redirect_uri?string

The redirect URI the authorization named. Required for authorization_code when it named one.

Formaturi
code_verifier?string

The PKCE code verifier. Required for authorization_code.

refresh_token?string

The refresh token. Required for refresh_token.

device_code?string

The device code from POST /oauth/device-authorization. Required for the device grant.

scope?string

Space-separated scopes, no wider than the grant, to narrow a refreshed token.

resource?string

The resource the token is for (RFC 8707).

Formaturi

Response body

About errors

Returns the access token, and a refresh token when the app asked for offline_access.

application/json
  1. response
access_token*string

The access token. Send it as Authorization: Bearer <token>.

token_type*"Bearer"

Always Bearer.

Value in"Bearer"
expires_in*integer

Seconds until the access token expires.

scope*string

Space-separated scopes the token holds.

refresh_token?string

The refresh token to spend for the next access token. Present when the grant holds offline_access.

An error in the shape RFC 6749 and RFC 8628 define. For example:

  • invalid_request: a required parameter is missing or repeated.
  • invalid_grant: the code or token isn't valid or has expired.
  • authorization_pending: the person hasn't approved the device code yet.
  • slow_down: you polled too soon.
  • access_denied or expired_token: the device code was denied or expired.
application/json
  1. response
error*string

The OAuth error code.

Value in"invalid_request""invalid_grant""unsupported_grant_type""unauthorized_client""invalid_scope""invalid_target""authorization_pending""slow_down""access_denied""expired_token"
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/token' \  -H 'Content-Type: application/x-www-form-urlencoded' \  -d 'grant_type=authorization_code&client_id=string'
About errors
{  "access_token": "marfa_at_2YotnFZFEjr1zCsicMWpAA",  "token_type": "Bearer",  "expires_in": 3600,  "scope": "core.note:read offline_access",  "refresh_token": "marfa_rt_tGzv3JOkF0XG5Qx2TlKWIA"}