# 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"
```

✓ Checkpoint: the response holds `access_token`, `token_type: "Bearer"`, `expires_in` (900 seconds by default), `refresh_token`, `active_context`, `contexts` and a signed `id_token`.

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

- [Contexts: one credential, one context](/docs/getting-started/contexts)
- [Create and rotate API keys](/docs/getting-started/api-keys)
- [Build a resident app with PKCE](/docs/guides/resident-app)

