- OAuth access token: the default for interactive use.
ironbee loginmints 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, the GitLab component, the Bitbucket Pipe or any CI pipeline where no browser is available.
OAuth tokens (default)
Runningironbee login opens Connect CLI in your browser, where the console authorizes the CLI for your current account once you’re signed in, 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.
Ctrl+C to cancel. The CLI prints the sign-in address too, so you can open it by hand. It opens only an http or https address, handing it to your system’s opener (open on macOS, xdg-open on Linux, the system’s rundll32 on Windows) without a shell; with a console URL of any other kind, it opens nothing and prints a warning. 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:
--collector-url; events are sent to {url}/v1/events. If the console answers the login with a shared account API key instead of a personal token, ironbee login stores it as service.apiKey.
Each token appears on the OAuth 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:
ironbee login again.
API keys (CI and automation)
For automation that runs without a browser, such as CI jobs, scheduled jobs and scripts, use an account API key instead. The GitHub Action and the GitLab component take it as theirironbee_api_key input, and the Bitbucket Pipe as its IRONBEE_API_KEY variable. 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:
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.
A credential never goes in a file inside the checkout: ironbee config set refuses it on the project and local layers. Keep it in the global config or in the environment. The repository’s personal file (--personal) can hold one too, but only ironbee review and ironbee credits read it: ironbee verify and your sessions’ event delivery don’t.
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, ironbee review and ironbee credits, which treat IRONBEE_API_KEY as a high-priority override, although an OAuth token from any source still wins over it), 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.
ironbee review and ironbee credits pick the credential in the same order as ironbee verify, IRONBEE_ACCESS_TOKEN included, but read it only from the flags, the environment, the repository’s personal file and the global config.
On a checkout whose remote is on a host other than github.com, gitlab.com and bitbucket.org, ironbee review, ironbee verify and your sessions’ background worker also use the credential to ask IronBee which hosts are your account’s GitHub and GitLab hosts. A credential of any role can. They need no token of the Git host for that.
What’s next?
OAuth 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.