kt auth

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

Login

On an interactive terminal, kt auth login starts the browser login flow:

kt auth login

Use --browser when you want to make that choice explicit:

kt auth login --browser

For a direct credential login, both --email and --password are required:

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 for the active profile and reused until you log out or the session expires. Direct password login places the password in the process arguments and may expose it through shell history or process inspection; prefer browser login for people and KEEPTRUSTS_API_TOKEN for headless automation.

Running kt auth login without flags in a non-interactive environment fails instead of silently choosing a credential flow.

Logout

Remove stored session credentials for the active profile:

kt auth logout

Whoami

Verify the active identity and API access context:

kt auth whoami

The response includes the current user, organization, project, role, authentication method, team memberships, capabilities, and resolved roles. Use it as a 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 team \
  --team-id team_abc123 \
  --role-id role_configurations_writer

The --scope flag sets the principal type (team or user). Team-scoped tokens also need --team-id. One or more --role-id flags are required and bind the token to specific IAM roles. 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.

Exchange an authorization code for a token

Use the dedicated token exchange command when a PKCE authorization flow returns an opaque code + code_verifier pair and you need a least-privilege API token exactly once:

kt token exchange-code \
  --code kt_ac_demo \
  --code-verifier replace-with-original-pkce-code-verifier-1234567890 \
  --client-id kt_client_demo \
  --redirect-uri https://your-app.example.com/oauth/callback \
  --token-name "CLI Access Key" \
  --purpose general \
  --scope org

Use --scope team --team-id <id> for a team authorization. Project scope requires at least one --project-id <id>; repeat the flag for additional projects. Organization scope cannot be combined with team or project IDs. The raw token is printed once on success and is not stored in the CLI profile, browser session, or console cookie state.

Exchange safety rules

• kt token exchange-code calls POST /v1/tokens/exchange-code.
• Success returns the raw token_value once and follows the same unified token model used by other governed tokens, including the canonical resource_id and resource_krn.
• The exchange response is marked Cache-Control: no-store and Pragma: no-cache.
• The CLI does not persist the revealed token into the local profile. Copy it into a secret manager or environment variable immediately.
• --scope, --team-id, and --project-id must match the original authorization request that produced the code.
• --redirect-uri must exactly match the caller's registered callback and the value used in that authorization request; Keeptrusts does not provide a generic console callback for customer applications.

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

# Verify identity
kt auth whoami

# Create a scoped token for CI
kt auth token create \
  --name "github-actions" \
  --scope team \
  --team-id team_abc123 \
  --role-id role_deploy

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

# Rotate an API token transactionally (revokes old, issues new in a single atomic operation)
kt token rotate tok_abc123

Interactive challenges

The CLI does not implement a separate terminal MFA prompt. When sign-in or a fresh-authentication challenge requires browser interaction, use kt auth login --browser and complete the flow there. An authorization error from a later command is not bypassed by switching to a broader token; use the identity and permission context reported by kt auth whoami to correct it.

Next steps

• CLI Overview
• CLI Command Groups
• kt token — unified API token management (create, rotate, delete)