Skip to main content
IronBee accepts two kinds of credentials, and the CLI picks the right one for you:
  • OAuth access token: the default for interactive use. ironbee login mints a personal token tied to your user and account. Each token is individually named and revocable.
  • API key: an account-scoped key for machine-to-machine (M2M) use, such as the GitHub Action or any CI pipeline where no browser is available.
Both are first-class and supported. The difference is who they identify: an OAuth token is you, an API key is the account.

​
OAuth tokens (default)

Running ironbee login opens your browser, asks you to authorize the CLI, and writes a personal access token to ~/.ironbee/config.json under service.oauthToken (older CLI versions wrote collector.oauthToken, which is still read as a fallback). It also persists service.domain — the stage you authenticated against — so the collector, API, and Console URLs all derive from one place (and any hand-set explicit URLs are dropped so they re-derive; pin the Console with --console-url if you need to). For a self-hosted deployment on non-standard hosts, no domain is inferred and the explicit URLs are kept instead. From then on the CLI authenticates as you, everywhere: event delivery to the Collector and the read-side API behind ironbee verify.
The login flow waits up to five minutes for you to confirm in the browser; press Ctrl+C to cancel. By default the token is named after your machine’s hostname so you can recognize it later in the Console and pass --name to set your own label:
Each token appears on the API Tokens page in the Console, where you can see when it was created, when it expires, and revoke it. CLI-minted tokens default to a 90-day lifetime.

​
Token limit

You can hold at most 10 OAuth access tokens per account at a time. This count includes expired tokens that you have not yet removed. If you are already at the limit, ironbee login cannot mint a new one and prints:
To free a slot, open the API Tokens page, revoke a token you no longer use, then run ironbee login again.

​
API keys (CI and automation)

For automation that runs without a browser; the GitHub Action, scheduled jobs, scripts, use an account API key instead. Supply it through the IRONBEE_SERVICE_API_KEY environment variable (the legacy IRONBEE_API_KEY still works) so it never lands in a committed file:
The CLI reads it into service.apiKey. You can also set it on disk with ironbee config set service.apiKey <key> --global, but the environment variable is preferred for CI because it overrides every config layer. Find and manage the account API key on the Account page in the Console. Owners and admins can view, copy, and rotate it.

​
Rotation and the grace window

Rotating the API key on the Account page generates a fresh key and keeps the previous key valid for 24 hours for a grace window so your CI and integrations keep working while you roll the new key out. Only one grace key exists at a time:
  • Rotating again while a grace key is still active permanently disables the earlier grace key (the Console asks you to confirm first).
  • Use Deactivate now on the Account page to end the grace window immediately.

​
Which credential the CLI uses

If both are present, the OAuth token takes priority on the wire. In practice: Both IRONBEE_SERVICE_OAUTH_TOKEN and IRONBEE_SERVICE_API_KEY override whatever is on disk, so a CI runner can supply a credential without touching ~/.ironbee/config.json. The legacy IRONBEE_OAUTH_TOKEN / IRONBEE_API_KEY forms fill only the deprecated collector.* fallback keys — they’re used only when the matching service.* key is unset (except by ironbee verify, which treats IRONBEE_API_KEY as a top-priority override), so on a machine that has run a recent ironbee login (which writes service.oauthToken) prefer the IRONBEE_SERVICE_* forms. See Environment variables for precedence details.

​
What’s next?

API Tokens in the Console

Create, name, and revoke your personal OAuth access tokens.

Account API key

View and rotate the shared account key used for CI.