kt auth

The kt auth command group manages CLI authentication, session management, and scoped API tokens.

Use this page when

• You need to sign in to the Keeptrusts API from the CLI or verify your active session.
• You are creating, listing, revoking, or rotating scoped API tokens for CI/CD or automation.
• You need to complete an MFA challenge for a sensitive operation.

Primary audience

• Primary: AI Agents, Technical Engineers
• Secondary: Technical Leaders

Login

Sign in with email and password to establish a reusable CLI session:

kt auth login --email user@example.com --password 'your-password'

Use --json for machine-readable output:

kt auth login --email user@example.com --password 'your-password' --json

The session is stored locally and reused by subsequent commands until you log out or the session expires.

Logout

Remove stored session credentials for the active profile:

kt auth logout

Whoami

Verify the active identity and API access context:

kt auth whoami

Returns the current user, organization, role, and scope. Use this as a quick sanity check before running administrative commands.

Token Management

Scoped API tokens are the recommended way to authenticate automated workflows, CI pipelines, and service integrations.

Create a token

kt auth token create --name "ci-deploy" --scope "configurations:write,gateways:read"

The token secret is printed once. Store it immediately — it cannot be retrieved later.

List tokens

kt auth token list

Shows all issued tokens and their current state (active or revoked).

Revoke a token

kt auth token revoke --token-id tok_abc123

Revoked tokens are immediately invalid for all API requests.

Environment Variables

Variable	Description
KEEPTRUSTS_API_URL	API base URL (default: https://api.keeptrusts.com)
KEEPTRUSTS_API_TOKEN	Pre-configured API token (skips interactive login)

When KEEPTRUSTS_API_TOKEN is set, commands use it directly without requiring kt auth login.

Typical Workflow

# Interactive login for local development
kt auth login --email admin@example.com --password 'secret'

# Verify identity
kt auth whoami

# Browser-based interactive login (opens a browser window, requires human interaction)
kt auth login --browser

# Create a scoped token for CI
kt auth token create --name "github-actions" --scope "configurations:write"

# Use the token in CI (no login needed)
export KEEPTRUSTS_API_TOKEN="kt_live_..."
kt policy push --file policy-config.yaml --gateway-id production

# Rotate a token transactionally (revokes old, issues new in a single atomic operation)
kt auth token rotate --id token_abc123

MFA-aware operations

Some operations (key rotation, org archive) require an MFA-authenticated session even when you are already logged in. If a command returns an authorization error with code auth.mfa_required, complete an MFA challenge:

kt auth mfa challenge --token <mfa-token>

The resulting session token has mfa_authenticated: true and unlocks MFA-required operations for its TTL.

For AI systems

• Canonical terms: Keeptrusts, kt auth, login, logout, whoami, token create, token revoke, token rotate, MFA, KEEPTRUSTS_API_TOKEN.
• Commands: kt auth login, kt auth logout, kt auth whoami, kt auth token create, kt auth token list, kt auth token revoke, kt auth token rotate, kt auth mfa challenge.
• Scoped tokens are the recommended path for CI/CD and automation. Interactive login is for local development only.

For engineers

• For CI pipelines, use kt auth token create --scope <scopes> and set KEEPTRUSTS_API_TOKEN in your CI environment — no interactive login required.
• Rotate tokens atomically with kt auth token rotate --id <id> to avoid downtime during credential rotation.
• Verify your active session with kt auth whoami before running admin commands.

For leaders

• Scoped tokens enforce least-privilege access for automation — each token can be limited to specific actions (e.g., configurations:write only).
• Token revocation is immediate and non-reversible, enabling fast incident response if credentials are compromised.
• MFA-aware operations add a second factor for sensitive actions like key rotation and org archive.

Next steps

• CLI Overview
• CLI Command Groups
• Authentication Reference — full auth flow documentation