Skip to main content

verdictan auth

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

Login​

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

verdictan auth login

To select browser login directly, use --browser:

verdictan auth login --browser

For a direct credential login, you must specify --email and --password:

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

Use --json for machine-readable output:

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

The CLI stores the session locally for the active profile. It reuses the session until you log out or the session expires. Direct password login puts the password in the process arguments. Shell history or process inspection can expose the password. Use browser login for personnel. Use VERDICTAN_API_TOKEN for headless automation.

If you run verdictan auth login without flags in a noninteractive environment, the command fails. It does not select a credential flow.

Logout​

Remove stored session credentials for the active profile:

verdictan auth logout

Whoami​

Verify the active identity and API access context:

verdictan auth whoami

The response includes the active user, organization, project, role, authentication method, team memberships, capabilities, and resolved roles. Before you run administrative commands, use it to verify the identity.

Token Management​

Use scoped API tokens to authenticate automated workflows, CI pipelines, and service integrations.

Create a token​

verdictan auth token create \
  --name "ci-deploy" \
  --scope team \
  --team-id team_abc123 \
  --role-id role_configurations_writer

The --scope flag sets the principal type to team or user. For a team token, you must also use --team-id. Use one or more --role-id flags to bind the token to specified IAM roles. Verdictan shows the token secret one time. Store it immediately. You cannot retrieve it again.

List tokens​

verdictan auth token list

The command shows all issued tokens and their state: active or revoked.

Revoke a token​

verdictan auth token revoke --token-id tok_abc123

Revoked tokens are immediately invalid for all API requests.

Exchange an authorization code for a token​

When a PKCE authorization flow returns a code and code_verifier pair, use the token exchange command. The command gives you one minimum-privilege API token.

verdictan token exchange-code \
  --code vdt_ac_demo \
  --code-verifier replace-with-original-pkce-code-verifier-1234567890 \
  --client-id vdt_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. For project scope, use one --project-id <id> flag for each project. Do not use organization scope with team or project IDs. When the exchange succeeds, Verdictan shows the raw token one time. The CLI does not store it in the CLI profile, browser session, or console cookie state.

Exchange safety rules​

  • verdictan token exchange-code calls POST /v1/tokens/exchange-code.
  • When an exchange succeeds, it returns the raw token_value one time. It uses the unified token model, including the canonical resource_id and resource_vrn.
  • The API marks the exchange response Cache-Control: no-store and Pragma: no-cache.
  • The CLI does not save the token from the exchange in the local profile. Immediately copy it to a secret manager or environment variable.
  • --scope, --team-id, and --project-id must match the authorization request that generated the code.
  • --redirect-uri must match the caller's registered callback and the value in the authorization request. Verdictan does not give a generic console callback for customer applications.

Environment Variables​

VariableDescription
VERDICTAN_API_URLAPI base URL (default: https://api.verdictan.com)
VERDICTAN_API_TOKENPreconfigured API token (skips interactive login)

When VERDICTAN_API_TOKEN is set, commands use it directly. You do not have to run verdictan auth login.

Typical Workflow​

# Interactive login for local development
verdictan auth login

# Verify identity
verdictan auth whoami

# Create a scoped token for CI
verdictan 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 VERDICTAN_API_TOKEN="vdt_..."
verdictan policy push --file policy-config.yaml --gateway-id production

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

Interactive challenges​

The CLI does not give a terminal MFA prompt. If a sign-in or new authentication challenge must use a browser, run verdictan auth login --browser. Complete the flow in the browser. A broader token does not bypass a new authorization error. Use the identity and permission context from verdictan auth whoami to correct the error.

Next steps​