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.
application/json- 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].
1 <= items <= 10scope?stringSpace-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.
length <= 1024client_name?stringThe app's name, which Marfa shows a person asked to approve it.
length <= 100client_uri?stringThe app's home page URL. Leave it out if the app has none.
length <= 512logo_uri?stringThe app's logo URL. Leave it out if the app has none.
length <= 512contacts?array<>Contact addresses for the app. Leave it out if there are none.
1 <= items <= 5tos_uri?stringThe app's terms of service URL. Leave it out if the app has none.
length <= 512policy_uri?stringThe app's privacy policy URL. Leave it out if the app has none.
length <= 512software_id?stringThe software's identifier. Leave it out if there is none.
length <= 100software_version?stringThe software's version. Leave it out if there is none.
length <= 100token_endpoint_auth_method?"none"none: the client is public and proves itself with PKCE. Any other method is refused with invalid_client_metadata.
1 <= length"none""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.
1 <= itemsresponse_types?array<>The response types the client uses. Defaults to code when grant_types includes authorization_code.
application_type?stringweb or native, which decides the redirect URIs the client may use. Defaults to web.
"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.
Returns the registered client, with its client_id.
application/json- response
redirect_uris?array<>The redirect URIs, as registered.
scope?stringSpace-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?stringThe app's name, as registered.
client_uri?stringThe app's home page URL, as registered. Absent if none was sent.
logo_uri?stringIcon URL for the application
contacts?array<string>List representing ways to contact people responsible for this client, typically email addresses
tos_uri?stringClient's terms of service uri
policy_uri?stringClient's policy uri
software_id?stringUnique identifier assigned by the developer to help in the dynamic registration process
software_version?stringVersion identifier for the software_id
token_endpoint_auth_method?"none"How the client proves itself at the token endpoint: none, for a public client.
"none"grant_types?array<string>The grants, as registered.
response_types?array<>The response types, as registered.
application_type?stringweb or native.
"web""native"client_id*stringUnique identifier for the client.
client_id_issued_at?numberWhen the client was registered, in seconds since the Unix epoch.
disabled?booleantrue if the client is disabled.
invalid_client_metadata: the body isn't sent asapplication/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- 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- response
error*"invalid_token"The OAuth error code.
"invalid_token"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/register' \ -H 'Content-Type: application/json' \ -d '{}'{ "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}