Apps

Authorize an app

Starts an authorization with PKCE (RFC 6749 and RFC 7636) and redirects the browser: to sign in, to the consent screen, or to the app's redirect URI with a code or an error, and the iss of the issuer.

GET
/oauth/authorize

Query parameters

response_type*"code"

The response type. Only code.

Value in"code"
client_id*string

The client ID from POST /oauth/register, or the URL of the app's client ID metadata document.

redirect_uri?string

One of the app's registered redirect URIs. Required when the app registered more than one.

Formaturi
code_challenge*string

The PKCE challenge: the base64url SHA-256 of your code verifier.

code_challenge_method*"S256"

The PKCE method. Only S256.

Value in"S256"
scope?string

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

state?string

A value Marfa returns unchanged on the redirect, so you can match it to your request.

resource?string

The resource the token is for (RFC 8707), such as the MCP endpoint's URL.

Formaturi
prompt?string

login asks the person to sign in again; none returns login_required or consent_required instead of showing a page.

Value in"login""none""consent"
max_age?integer

How many seconds ago the person may have signed in. If they signed in longer ago, Marfa asks them to sign in again before it answers, as 401 insufficient_user_authentication asks; 0 always asks.

Range0 <= value

Response body

About errors

Redirects the browser. Location is the sign-in page, the consent screen, or the app's redirect URI with code, state and iss, or with error and error_description.

An RFC 6749 error, when Marfa can't send the browser back to the app:

  • invalid_request: client_id is missing, or a parameter is repeated.
  • invalid_client or invalid_client_metadata: the client ID metadata document is unreadable or invalid.
  • invalid_target: a resource isn't served here.

X-Marfa-Reach gets validation_error.

application/json
  1. response

An error response.

error*

What went wrong.

  • forbidden: the request carries the owner's browser session, and the sign-in address isn't HTTPS or on this machine.
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.

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 GET 'http://localhost:8600/oauth/authorize?response_type=code&client_id=string&code_challenge=string&code_challenge_method=S256&max_age=300'
About errors
Empty