# Authentication

`cademi auth login` connects the CLI to your account and saves the connection as a profile. Use human mode when a person runs the CLI, so every call is attributed to an administrator, and autonomous mode for scripts and CI.

| Mode | What the CLI sends | Use it for |
|---|---|---|
| Human | The administrator's OAuth access token and the credential secret | Interactive use. The audit trail records the administrator as the author. |
| Autonomous | The credential secret only | Scripts, CI, and servers. |

In both modes, the credential's policy determines what each call can do. See [Authentication](https://cademi.dev/api/authentication.md) and [Permissions and scope](https://cademi.dev/api/access-control.md) for the API side.

## Human mode

You need:

- An administrator who is signed in to the Cademí dashboard with two-factor authentication completed.
- A credential that allows human mode (`auth_mode` set to `both` or `human_required`) and is linked to that administrator, with its secret (`ck_live_...` or `ck_test_...`).

```sh
cademi auth login
```

1. The CLI asks for the platform URL. Press Enter to accept the default: the URL already saved in that profile or, for a new profile, `https://api.cademi.com.br`. Pass `--base-url` (or set `CADEMI_BASE_URL`) to skip the question.
2. The browser opens on the authorization page. The administrator approves access, and the browser returns to the CLI. The CLI waits up to 5 minutes. With `--no-browser`, or when the browser cannot be opened, the CLI prints the authorization URL instead: open it in a browser on the same machine, because the authorization returns to a local address.
3. The CLI asks for the credential secret. The input is hidden, and a value that does not start with `ck_live_` or `ck_test_` is rejected.
4. The CLI checks both values with `GET /credentials/current`, saves the profile, and makes it the current profile.

The CLI renews the access token on its own. When the session can no longer be renewed, for example after it was revoked, commands fail with exit code `3` and ask you to run `cademi auth login` again.

If the credential does not allow human mode, the API returns `403 human_mode_not_allowed`: sign in with `--api-key-only` instead. The OAuth flow itself is described in [Human mode (OAuth)](https://cademi.dev/api/oauth.md).

## Autonomous mode

```sh
cademi auth login --api-key-only
```

The CLI asks for the platform URL and the credential secret, checks the credential, and saves the profile. With `--with-key`, the CLI reads the secret from standard input instead of asking for it. Without a terminal, `--with-key` is required: the CLI cannot ask for the secret and exits with code `2`.

```sh
echo "$CADEMI_KEY" | cademi auth login --api-key-only --with-key --profile ci
```

Without a terminal, the CLI does not ask for the platform URL: it uses `--base-url` or `CADEMI_BASE_URL`, the URL already saved in that profile, or `https://api.cademi.com.br`.

A credential with `auth_mode` set to `human_required` cannot be used in autonomous mode: the CLI refuses it with exit code `2`.

### Without a profile: `CADEMI_API_KEY`

When `CADEMI_API_KEY` is set, every command uses that secret in autonomous mode, without reading the keychain or any saved credential. The variable takes precedence over every profile.

```sh
export CADEMI_API_KEY=ck_test_...
cademi credentials current
```

The platform URL comes from `--base-url`, then `CADEMI_BASE_URL`, then the selected profile, and finally `https://api.cademi.com.br`. This is the recommended setup for CI ([CI and automation](https://cademi.dev/cli/ci.md)).

## Profiles

A profile is a saved connection: platform URL, mode, environment, credential ID and name, and, in human mode, the administrator. `cademi auth login` saves the profile as `default` unless you name it with `--profile`, and makes it the current profile. Signing in again with the same name replaces that profile.

```sh
cademi auth login --profile sandbox
cademi profiles list                    # * marks the current profile
cademi profiles use sandbox             # same as: cademi auth switch sandbox
cademi --profile production products list
```

To choose the profile for a command, in order of precedence:

1. `--profile <name>` or `-p <name>` on the command.
2. The `CADEMI_PROFILE` environment variable.
3. The current profile, set by the last `cademi auth login` or by `cademi profiles use`.

The environment (`production` or `sandbox`) is the environment of the credential. The CLI highlights `production` in red, and confirmation prompts for destructive commands start with `[production]` when the profile is a production profile.

## Checking the current credentials

```sh
cademi auth status
```

`cademi auth status` validates the credential against the API and shows the profile, the platform URL, the environment, the credential ID, name, and status, the mode in use and the modes the credential allows, the number of policy grants, and the API release of the server. In human mode it also shows the administrator and when the access token expires.

With `--json`, it prints an object with `profile`, `release`, and `credential`, where `credential` is the response of `GET /credentials/current`. For the effective permissions, run `cademi credentials current-policies`.

## Signing out

```sh
cademi auth logout
cademi auth logout --profile sandbox
```

`cademi auth logout` revokes the profile's OAuth tokens, removes its secrets from the keychain, and deletes the profile. If it was the current profile, the first remaining profile in alphabetical order becomes the current one. If the revocation request fails, the local secrets are still removed, the command exits with code `1`, and the tokens stay valid until they expire (1 hour for the access token, 30 days for the refresh token).

Signing out does not revoke the credential, which other people or systems may share. Revoke it in the Cademí dashboard or with `cademi credentials delete <credential_id>`.

## Where secrets are stored

| Data | Location |
|---|---|
| Credential secret, OAuth tokens, and the local signing secret of `cademi listen` | The operating system keychain: Keychain on macOS, Credential Manager on Windows, Secret Service on Linux. Entries use the service name `cademi-cli`. |
| Profiles, without secrets | `config.toml` in the configuration directory, readable only by your user. `cademi env config_dir` shows the directory, and `CADEMI_CONFIG_DIR` changes it. |

Secrets are never written to files, and `--debug` never logs them. On a machine without a keychain, such as a container or a headless Linux server, commands that need a profile fail with a message that points to `CADEMI_API_KEY`: use the environment variable there.

Every request also carries the `X-Client: cademi-cli`, `X-Client-Version`, and `X-Client-Install-Id` headers, so your calls are identifiable in the audit trail. These headers do not grant any access.