Authentication

Which credential each client should use (API key, OAuth with PKCE or device grant), how to send it, and what the API returns when it refuses one.

Every authenticated request sends its credential in the Authorization header with the Bearer scheme. What differs is where the credential comes from: an API key for servers, an OAuth token obtained with PKCE for apps where a person signs in, or a token obtained through the device grant for command-line tools.

Client Credential Where you get it
Server, scheduled job, integration API key (sk_live_, sk_rlive_, sk_test_, sk_rtest_) Developers > API keys in the dashboard
Web or mobile app with a person's session OAuth access token (Authorization Code with PKCE) /oauth/authorize and /oauth/token
Command line or device without a browser OAuth access token (device grant) /oauth/device_authorization and /oauth/token

Keep API keys out of code that runs in a browser or ships inside a mobile app: anyone who extracts a key acts with all of its scopes.

API keys#

bash
curl -sS "$BUSINESS_API/customers?limit=1" \
  -H "Authorization: Bearer $API_KEY"

When the credential is missing or refused, the response is 401 as application/problem+json. If you sent a Bearer token, the response also carries WWW-Authenticate: Bearer error="invalid_token", which tells the client to refresh the token rather than ask the person to sign in again.

json
{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Credentials have been revoked",
  "instance": "$BUSINESS_API/customers",
  "code": "UNAUTHORIZED",
  "error_code": "auth.unauthenticated",
  "request_id": "req_9c1e4b7a2f6d48e0b3a5c8d1f7e2a940"
}

The detail tells a revoked key (Credentials have been revoked) from an expired one (Credentials have expired) or an unknown one (Invalid or missing authentication credentials). A key with Allowed addresses is also refused with 401 when the request comes from another address. The type field points to the site's error page when the operator has configured the site origin, and is about:blank otherwise.

OAuth 2.0 with PKCE#

OAuth clients are public (no client secret) and the installation's operator registers them under security.oauth.clients, each with its id and allowed redirect_uris. The discovery document at https://api.gota.umbeluzi.com/.well-known/oauth-authorization-server lists the endpoints, code_challenge_methods_supported: ["S256"] and the scopes openid, offline_access, profile and email.

  1. Generate a random code_verifier and its SHA-256 code_challenge.
  2. Send the person to /oauth/authorize with response_type=code, client_id, redirect_uri, state, code_challenge and code_challenge_method=S256. Without code_challenge, or with another method, the redirect comes back with error=invalid_request.
  3. Exchange the code you receive for tokens:
bash
curl -sS -X POST "https://api.gota.umbeluzi.com/oauth/token" \
  -d grant_type=authorization_code \
  -d client_id=resident-app \
  -d code="$CODE" \
  -d redirect_uri="$REDIRECT_URI" \
  -d code_verifier="$CODE_VERIFIER"

The /oauth/* endpoints refuse requests authenticated with an API key.

Device grant#

For command-line tools, POST /oauth/device_authorization with client_id returns device_code, user_code, verification_uri, verification_uri_complete, expires_in and interval. The person opens the address and confirms the code; meanwhile the client polls /oauth/token with grant_type=urn:ietf:params:oauth:grant-type:device_code and gets authorization_pending, slow_down, expired_token or access_denied until the authorization completes.

The CLI does this with gotactl auth login. Its flags are --web (sign in through a browser with PKCE), --with-api-key (read an API key from stdin and store it in the keychain) and --context (sign in straight to a context by its ID). gotactl auth status shows the active profile and issuer.

Next steps#