# Authentication

A **connection = environment + tenant**. Each connection ("profile") records its
own auth. Profiles live in `~/.tillit/config.json`, named `{tenant}-{environment}`.

Base URL is a per-tenant subdomain derived from the environment (override with
`--base-url`):

| Environment | Base URL |
| ----------- | -------- |
| `prod` | `https://{tenant}.tillit.cloud` |
| `stage` | `https://{tenant}.tillit-stage.cloud` |
| `sandbox` | `https://{tenant}.tillit-sandbox.cloud` |
| `dev` | `https://{tenant}.tillit-dev.cloud` |

## Region

Every connection records a region (`eu`, `us`, or `au`). API calls are routed
through the regional gateway path, so requests go to `${baseUrl}/eu/api/...`,
`${baseUrl}/us/api/...`, or `${baseUrl}/au/api/...`. The region is required at
`tllt configure` time; pass `-r/--region eu|us|au` (non-interactive) or pick it
at the prompt.

## Method 1 — basic auth

```bash
tllt configure -t acme -e prod -r eu -a basic -u alice -w 's3cret'
```

Sends `Authorization: Basic base64(<username>@<tenant>.tillit.cloud:<password>)`
plus the `tillit-tenant: <tenant>` header.

- Works against **both** the DO and Scheduler APIs.

## Method 2 — api key + secret (Cognito bearer token)

The api key is a Cognito app-client id; the secret is its client secret. The CLI
performs the OAuth2 `client_credentials` flow against the tenant's Cognito token
endpoint, then uses the returned access token as a bearer token.

```bash
tllt configure -t acme -e prod -r eu -a apikey \
  --api-key <clientId> --api-secret <secret> \
  --token-url https://<domain>.auth.<region>.amazoncognito.com/oauth2/token \
  --scopes 'api/*.read,api/*.write'
```

Sends `Authorization: Bearer <token>` plus `tillit-tenant: <tenant>`.

- Works against both DO and Scheduler.
- Tokens are cached in `~/.tillit/tokens.json` until shortly before expiry.
- `--token-url` is the Cognito hosted-domain token endpoint
  (`.../oauth2/token`). Ask the platform team if you don't know the domain.

## Files

| Path | Contents |
| ---- | -------- |
| `~/.tillit/config.json` | profiles (mode 600) |
| `~/.tillit/tokens.json` | cached bearer tokens (mode 600) |
| `~/.tillit/.env` | legacy format from older CLI versions, still read |