OAuth for apps

Use OAuth when your app acts for other people. Atrix runs a standard OAuth 2.1 authorization server: authorization code with PKCE, public clients, dynamic registration. There is no client secret, because a secret shipped to a laptop or a browser is a secret in a screenshot.

Discovery#

Clients that follow RFC 8414 and RFC 9728 need only the API URL; everything else is found from these documents.

curl https://atrix.dev/.well-known/oauth-authorization-server
curl https://atrix.dev/.well-known/oauth-protected-resource

1. Register your app#

Register once with your redirect addresses. They must be https, or http on a loopback address, with no fragment. Clients that publish a client ID metadata document can skip this step.

curl -X POST https://atrix.dev/api/oauth/register \
  -H "Content-Type: application/json" \
  -d '{"client_name":"My App","redirect_uris":["https://myapp.com/callback"]}'

2. Send the person to authorize#

Make a PKCE verifier and its S256 challenge, then redirect. Ask only for the scopes you need, separated by spaces; add offline_access for a refresh token.

https://atrix.dev/api/oauth/authorize
  ?response_type=code
  &client_id=CLIENT_ID
  &redirect_uri=https://myapp.com/callback
  &scope=work.read%20work.write%20offline_access
  &state=RANDOM_STATE
  &code_challenge=CHALLENGE
  &code_challenge_method=S256

The consent screen shows each scope in plain words. Scopes the person cannot exercise are shown greyed out with the reason, and are not granted.

3. Exchange the code#

Codes live for 60 seconds and work once.

curl -X POST https://atrix.dev/api/oauth/token \
  -d grant_type=authorization_code \
  -d code=CODE \
  -d redirect_uri=https://myapp.com/callback \
  -d client_id=CLIENT_ID \
  -d code_verifier=VERIFIER

Token lifetimes#