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 of the account who has two-factor authentication turned on. The browser flow asks them to sign in and complete two-factor authentication.
• 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
cademi auth login --platform acme.cademi.com.br

1. The CLI asks for the Cademí API 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. This is the address of the API, not of your account.
2. The browser opens on the authorization page, which asks for your account's address. With --platform, the page skips that question (Choosing the account). The administrator signs in to the account, completes two-factor authentication, and chooses Authorize. The browser then returns to the CLI, which 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).

Choosing the account

--platform takes your account's address: acme.cademi.com.br, the subdomain alone (acme), or the account's custom domain. The CLI saves the address in the profile and reuses it the next time you run cademi auth login for that profile, so you pass it only once. To change it, pass --platform with another address. To clear it, pass --platform=, and the authorization page asks for the address again. cademi auth status and cademi env show the saved address. How the authorization page handles the address is described in Choosing a platform.

When the authorization fails

If the browser returns without an authorization, the CLI stops the login right away, prints the reason, and exits with code 1. Nothing is saved.

For any other reason, the CLI prints the description it receives. The protocol side of these refusals is described in Human mode (OAuth).

The CLI also checks the iss parameter of the response (RFC 9207). It refuses a response whose iss differs from the issuer in the discovery document of the API URL, and a response without iss when that document sets authorization_response_iss_parameter_supported to true. The login then stops in the same way.

Autonomous mode

cademi auth login --api-key-only

The CLI asks for the Cademí API 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 API 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 API rejects it with 401 human_context_required, and the CLI exits with code 3. The error suggests signing in with cademi auth login without --api-key-only, or using a credential that allows autonomous mode.

Without a profile: CADEMI_API_KEY

When CADEMI_API_KEY is set, commands that call the API use 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 API 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: API URL, account address (when you pass --platform), 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 or CADEMI_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 API URL, the account address saved with --platform (when there is one), 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 credential object returned by 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 run cademi credentials update <credential_id> -f status=revoked with another credential that has the credentials.manage permission.

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.