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#
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.
{
"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.
- Generate a random
code_verifierand its SHA-256code_challenge. - Send the person to
/oauth/authorizewithresponse_type=code,client_id,redirect_uri,state,code_challengeandcode_challenge_method=S256. Withoutcode_challenge, or with another method, the redirect comes back witherror=invalid_request. - Exchange the code you receive for tokens:
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.