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 acts as an administrator, and autonomous mode for scripts and CI.

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. No API credential is needed.

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 checks the session with GET /capabilities, 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.

--with-key applies only with --api-key-only: in human mode, the CLI ignores it and prints a warning. Human profiles saved by earlier versions of the CLI keep working without a new login; the credential secret they saved is not used. CLI 0.3.x sends the access token together with the credential secret, and the API rejects those calls with 401 ambiguous_credentials; run cademi update to get a version that sends the access token alone. The OAuth flow itself is described in Administrators (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 in both modes, including --api-key-only, and the next cademi auth login in human mode for that profile reuses it, 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, cademi profiles list, 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 Administrators (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.

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 integrations 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 and, in autonomous mode, the credential ID and name or, in human mode, the administrator and the account. 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 content products list

cademi profiles list shows one row per profile, with the API URL in API and the account address saved with --platform in PLATFORM (- when there is none):

   NAME     API                        PLATFORM            ENVIRONMENT  MODE   CREDENTIAL
   ci       https://api.cademi.com.br  -                   sandbox      key    key_01J8Z6 ("CI")
*  default  https://api.cademi.com.br  acme.cademi.com.br  production   human  administrator adm_42

With --json, each profile is an object with name, current, base_url, platform, auth_mode, environment, key_id, key_name, admin_id, and account_id. Secrets are never included.

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 or, in human mode, of the account. 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

In autonomous mode, cademi auth status validates the credential with GET /credentials/current 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, the number of policy grants, and the API release of the server. 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 integrations credentials current-policies.

In human mode, no credential is involved: cademi auth status checks the session with GET /capabilities and shows the profile, the API URL, the account address, the environment, the administrator (adm_...), the account (ins_...), the mode, when the access token expires, the number of permissions in effect, and the API release of the server. With --json, it prints an object with profile, release, environment, administrator, capabilities, and access_token_expires_at. For the permissions themselves, run cademi account capabilities get.

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 integrations 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. When CADEMI_CLIENT_REQUEST_ID is set, they also carry X-Client-Request-Id with that value (Environment variables). These headers do not grant any access.