Authentication

Kheeper uses public key authentication for both the CLI and the container registry. Your private key never leaves your workstation.

How it works

When you log in with kheeper auth login, the CLI generates an Ed25519 keypair locally. It produces a registration token — a short-lived JWT that proves you control the private key — which you upload to the Kheeper dashboard. Once the key is registered, the CLI uses it to sign JWTs for all API and registry operations.

Logging in

Visit the dashboard keys page to find your user ID.
Run kheeper auth login with your user ID:

kheeper auth login <user_id>

The CLI prints a registration token. Copy and paste it into the dashboard keys page.
The CLI waits until the key is registered, then confirms success.

By default, kheeper auth login also configures Podman to use the Kheeper credential helper. Pass --podman=false to skip this.

Verifying your session

kheeper status

This confirms your CLI is authenticated and shows which context you're using.

Registry authentication

The docker-credential-kheeper binary acts as a credential helper for Podman. When Podman needs to push or pull from kheeper.com, it calls the credential helper, which signs a fresh JWT using your local private key.

If you need to set up the credential helper separately:

kheeper auth setup-podman

This writes the credential helper configuration to your Podman auth config.

Generating tokens

Tokens are generated automatically when needed for registry and API calls. To generate a token manually:

kheeper auth token

The default TTL is 1 hour. Use --ttl to customize:

kheeper auth token --ttl 24h

Contexts

Contexts let you maintain multiple authenticated sessions — for example, one for production and one for a staging environment.

# Log in to a different origin with a named context
kheeper auth login <user_id> --context staging

# Switch contexts
kheeper contexts set staging

# List contexts
kheeper contexts list

Bot users

Bot users provide non-interactive authentication for CI/CD pipelines and automated systems. Bots belong to an org and use the same public key authentication as human users.

# Create a bot
kheeper bots create myorg/ci-bot

# List bots in an org
kheeper bots list myorg

Bots can be granted specific repository permissions via authorizations.

Repo access control

Org owners have full read and write access to all repositories in their org. To grant access to other users or bots, use authorizations:

# Grant read access
kheeper authorizations create myorg/myrepo --email user@example.com --permission reader

# Grant write access
kheeper authorizations create myorg/myrepo --email user@example.com --permission writer

Permissions:

reader — can pull images from the repo
writer — can push images to the repo

Logging out

# Remove credentials for the current context
kheeper auth logout

# Remove credentials for all contexts
kheeper auth logout --all