Skip to main content

CLI and AI agent login

Suggested reading

Read the Identity overview first for the token flows Hub supports.

When you're at a terminal rather than a browser, hub-credential-helper logs you into Hub through the OAuth 2.0 Device Authorization Grant (RFC 8628) and caches the result. Anything that can read a bearer token off stdout — curl, a script, an AI agent such as Claude Code — then works against Hub without handling credentials itself.

Install the binary and run hub-credential-helper --help for the full flag and environment-variable reference. This page covers the two commands you need.

Log in​

hub-credential-helper login --hub-url=https://hub.example.com

The helper prints a short user code and a verification URL. Open the URL in any browser, sign in with your IdP, and approve the code. On approval the helper caches a Hub access token and a refresh token on disk, so one login backs every subsequent call. Refresh tokens last 90 days and are reaped after 90 days of disuse, so an actively used login effectively keeps working.

get-token returns a cached, auto-refreshed Hub JWT on stdout:

curl -H "Authorization: Bearer $(hub-credential-helper get-token \
  --hub-url=https://hub.example.com)" \
  https://hub.example.com/apis/hub.upbound.io/v1beta1/resources

Wherever this documentation shows an Authorization: Bearer <hub-token> header, $(hub-credential-helper get-token ...) produces that token. Pass --output json instead to get the token with its expiry, which is the form an agent or a script usually wants.

Tokens are cached under --cache-dir (HUB_CACHE_DIR). To bypass the cache and force a fresh token, pass --no-cache, or delete the cache directory.

tip

For day-to-day Hub work, prefer kubectl login over passing tokens around — the credential plugin refreshes on every command, so there's no token in your shell history or environment.

How revocation works​

Every device-flow login creates a server-side record on Hub, and the client's refresh token is only useful while that record exists. A refresh token copied off a developer's disk is inert on its own, and Hub reaps records after 90 days of inactivity.

note

Hub doesn't yet expose an API for listing or revoking your own sessions. Revoking a specific login before it ages out is an operator-side database operation today.