Apps

Register an app

Registers an app as an OAuth client and returns it with its client_id. Send no credential; a web page can call it from a browser on any origin. The client_credentials grant isn't available: a program that acts for no person uses an API key.

POST
/oauth/register

Request body

application/json
  1. body

An OAuth client: its app metadata and the grants it uses. Marfa ignores metadata it doesn't support and leaves it out of the answer.

redirect_uris?array<>

The addresses Marfa may send a person back to after authorization. Required for authorization_code. At most 10. A web client's URIs must use https off the loopback; a native client may use http on localhost, 127.0.0.1 or [::1].

Items1 <= items <= 10
scope?string

Space-separated scopes to register the client for. offline_access needs refresh_token or authorization_code in grant_types. Leave it out for your content and links: content:read content:write edge.*:read edge.*:write offline_access.

Lengthlength <= 1024
client_name?string

The app's name, which Marfa shows a person asked to approve it.

Lengthlength <= 100
client_uri?string

The app's home page URL. Leave it out if the app has none.

Lengthlength <= 512
logo_uri?string

The app's logo URL. Leave it out if the app has none.

Lengthlength <= 512
contacts?array<>

Contact addresses for the app. Leave it out if there are none.

Items1 <= items <= 5
tos_uri?string

The app's terms of service URL. Leave it out if the app has none.

Lengthlength <= 512
policy_uri?string

The app's privacy policy URL. Leave it out if the app has none.

Lengthlength <= 512
software_id?string

The software's identifier. Leave it out if there is none.

Lengthlength <= 100
software_version?string

The software's version. Leave it out if there is none.

Lengthlength <= 100
token_endpoint_auth_method?"none"

none: the client is public and proves itself with PKCE. Any other method is refused with invalid_client_metadata.

Length1 <= length
Default"none"
Value in"none"
grant_types?array<>

The grants the client uses: authorization_code, refresh_token or urn:ietf:params:oauth:grant-type:device_code. Defaults to authorization_code. Without authorization_code, add refresh_token to get a refresh token with offline_access.

Items1 <= items
response_types?array<>

The response types the client uses. Defaults to code when grant_types includes authorization_code.

application_type?string

web or native, which decides the redirect URIs the client may use. Defaults to web.

Value in"web""native"
resources?array<string>

Resource identifiers, each an absolute URI without a fragment; any other value is refused with invalid_target. Marfa doesn't register them or return them: a token request names its own resource.

Response body

About errors

Returns the registered client, with its client_id.

application/json
  1. response
redirect_uris?array<>

The redirect URIs, as registered.

scope?string

Space-separated scopes the client is registered for: the ones you named, or content:read content:write edge.*:read edge.*:write offline_access when you named none, without offline_access for a client that can't use a refresh token.

client_name?string

The app's name, as registered.

client_uri?string

The app's home page URL, as registered. Absent if none was sent.

logo_uri?string

Icon URL for the application

contacts?array<string>

List representing ways to contact people responsible for this client, typically email addresses

tos_uri?string

Client's terms of service uri

policy_uri?string

Client's policy uri

software_id?string

Unique identifier assigned by the developer to help in the dynamic registration process

software_version?string

Version identifier for the software_id

token_endpoint_auth_method?"none"

How the client proves itself at the token endpoint: none, for a public client.

Value in"none"
grant_types?array<string>

The grants, as registered.

response_types?array<>

The response types, as registered.

application_type?string

web or native.

Value in"web""native"
client_id*string

Unique identifier for the client.

client_id_issued_at?number

When the client was registered, in seconds since the Unix epoch.

disabled?boolean

true if the client is disabled.

  • invalid_client_metadata: the body isn't sent as application/json, or client metadata is invalid or too long.
  • invalid_redirect_uri: a redirect URI is invalid or too long, or there are more than 10.
  • invalid_scope: a scope is not allowed.
  • invalid_target: a resource is invalid.

These errors use RFC 7591. An unknown query parameter gets Marfa's validation_error.

application/json
  1. response

An error response.

error*

What went wrong.

An error in the shape RFC 6750 defines:

  • invalid_token: the request sends a bearer token, such as an API key. Register with no credential.
application/json
  1. response
error*"invalid_token"

The OAuth error code.

Value in"invalid_token"
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/register' \  -H 'Content-Type: application/json' \  -d '{}'
About errors
{  "application_type": "web",  "token_endpoint_auth_method": "none",  "grant_types": [    "authorization_code",    "refresh_token"  ],  "response_types": [    "code"  ],  "redirect_uris": [    "https://notes.example.com/callback"  ],  "scope": "core.note:read offline_access",  "client_name": "Notes Companion",  "client_id": "01a10126-97a4-788d-8098-07948d5ea997",  "client_id_issued_at": 1791019800}