Authentication
The mapbox auth commands sign the CLI in to your Mapbox account and
manage the token every other command uses. There are five:
Credentials live in ~/.mapbox, one file per profile, or in whatever
directory MAPBOX_CONFIG_DIR names when it's set. The commands take
--profile <name>, which credential file to act on, defaulting to
default (auth profiles is the exception; see below). login, logout
and refresh also take --dry-run, which describes what would change
without changing it.
mapbox auth login
Registers an OAuth client, opens the browser for the authorization code, and exchanges it for a token. Requires an interactive terminal and a browser; for scripts or CI, use MAPBOX_ACCESS_TOKEN instead.
Examples:
mapbox auth login # default profile
mapbox auth login --profile work # a second account, side by side
mapbox auth logout
Deletes the locally stored credentials file for the selected profile. This does not revoke the associated access or refresh token — the token can still be used until it expires.
Examples:
mapbox auth logout
mapbox auth logout --profile work -o json
mapbox auth refresh
Forces a token refresh regardless of expiry.
Examples:
mapbox auth refresh
mapbox auth refresh --profile work
mapbox auth whoami
Reports the token the next command will use and whose it is, without refreshing it. mapbox auth status is an alias.
Parameters:
| Parameter | Description |
|---|---|
--verify | Confirm the token against the Mapbox API instead of only reading it locally — a revoked token still looks perfectly valid when read from disk. Any verdict but valid fails with its own code: token_expired, token_revoked, token_invalid or token_malformed. |
Examples:
mapbox auth whoami
mapbox auth whoami --profile work
mapbox auth whoami --verify
mapbox auth profiles
Lists every profile with credentials stored on disk, not only the one
--profile would select. whoami answers which token the next command will
use; this answers what's stored at all, for when you've forgotten which
named profiles you've logged into. It only reads, never refreshing a token,
and ignores --token and MAPBOX_ACCESS_TOKEN. Passing --profile changes
nothing and prints a warning.
Examples:
mapbox auth profiles