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.

In both modes, the credential's policy determines what each call can do. See Authentication and Permissions and scope 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_...).

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).

Autonomous mode

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.

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.

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).

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.

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

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

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

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.