Skip to main content
APIContext
Talk to salesStart free
Start HereGuidesConceptsCLIReferenceChangelogStatus

Authentication

The apimetrics CLI authenticates with OAuth 2.0. There is no API key environment variable and no api configure command: sign in with login. Most commands auto-trigger login when they need credentials, so running login explicitly is rarely required.

login​

Log in to APImetrics. The default interactive flow uses the OAuth 2.0 authorization-code flow with PKCE (code_challenge_method=S256) and opens your browser to complete sign-in.

apimetrics login
# Sign in interactively (browser-based, auth-code + PKCE)
apimetrics login

login --device​

Use the --device flag to sign in by confirming a short code in a browser on any device, instead of being redirected back to the machine running the CLI. This is the right choice over SSH, in a container, or anywhere the browser cannot reach localhost.

apimetrics login --device

The CLI prints a code and a verification address. Open the address in a browser on any device, confirm the code, and the CLI finishes signing in. For the underlying protocol, see Device Code Authorization flow.

How long a login lasts​

A browser or device-code login stays valid while you use it: when the access token expires, the CLI renews it in the background without opening the browser. Run apimetrics login again after 3 days without using the CLI, or 7 days after you signed in, whichever comes first. Commands that need credentials start the login for you.

logout​

Remove the cached login credentials and the active project, forcing re-authentication on the next request.

apimetrics logout
apimetrics logout

Service accounts​

A service account authenticates without a browser, which makes the CLI usable from CI, cron jobs, and other headless environments. Create one in your organization's settings (see Organizations) and download the JSON file it gives you:

{
  "name": "ci-runner",
  "client_id": "...",
  "client_secret": "...",
  "audience": "https://client.apimetrics.io"
}

Point the CLI at that file with --service-account. Every request then authenticates with the OAuth 2.0 client-credentials grant instead of the cached browser login:

apimetrics list-monitors --service-account ./ci-runner.apimetrics.json

You can also set the file path in an environment variable, which is the preferred approach in CI:

export APIMETRICS_SERVICE_ACCOUNT=/secrets/ci-runner.apimetrics.json
apimetrics list-monitors
danger

The file holds a live secret. Keep it out of version control.

Choosing a project​

Service accounts are granted access to specific projects, and headless runs cannot answer an interactive project prompt. Name the project for the run with --project-id, or set APIMETRICS_PROJECT_ID:

apimetrics list-monitors \
  --service-account /secrets/ci-runner.apimetrics.json \
  --project-id <project-id>

--project-id applies to that run only and never overwrites the project saved by project select. To see which projects a service account can reach, run apimetrics project select --service-account <file> from a terminal.

Service account behavior​

  • Access tokens last an hour and are cached per set of credentials. A service account never uses your interactive login's token, or another service account's. Rotating the secret invalidates the cache.
  • The client-credentials grant issues no refresh token, so when the access token expires the CLI requests a new one.
  • apimetrics login --service-account <file> fetches a token without making an API call, which is a quick way to check that credentials work.
  • apimetrics logout --service-account <file> drops that account's cached token and leaves your browser login and selected project alone.

OAuth 2.0 flows​

The CLI supports three OAuth 2.0 flows:

FlowWhen to use
Authorization code + PKCE (S256)Default for interactive/human login. Opens a browser.
Device codeInteractive login when the browser is on another device, such as over SSH. Use login --device.
Client credentialsMachine-to-machine / unattended automation (CI, agents) with no browser. Used by service accounts.

The interactive login command uses authorization-code + PKCE against the binary's configured authorization server. For client-credentials, use a service account.

Named profiles​

Use the global -p/--rsh-profile flag to keep separate credential sets (for example, interactive vs. machine-to-machine, or staging vs. production). The default profile is named default.

# Use a profile named "ci" (e.g. configured for client-credentials)
apimetrics list-monitors -p ci -o json

See Global flags for the full --rsh-* flag list.

See also​