Authentication and environments

Credential types

Credential	Intended use
Console session	Workspace administration and customer management routes under /api/v1
Environment API key	Evaluation and provider proxy requests; keep this key on your server
Device handle	Edge, local MCP, and interactive operator login
Operator token	Non-interactive operator CLI work, with a role capped by the issuer
Account OAuth grant	Read-only account MCP tools within the granted scope
SCIM token	Enterprise user provisioning, separate from application keys

These credentials are not interchangeable. /v1/checkpoints accepts device/API credentials, while the console uses /api/v1/checkpoints. Approving or denying requires an authorized human membership; an API key alone is not a human approver.

Edge and operator login

kastra-edge login
kastra-edge status
kastra-edge config show

Complete the device flow in your browser and check the returned workspace. kastra auth login is the operator CLI equivalent. Both tools share the selected configuration: KASTRA_CONFIG, otherwise $XDG_CONFIG_HOME/kastra/config.toml when set, otherwise ~/.kastra/config.toml. Do not edit device handles or workspace identity fields by hand.

kastra-edge config set default_environment dev

Use an environment that exists in your workspace. API keys carry an environment context. Console APIs generally accept environment_id or X-Environment-ID; legacy name parameters remain on some routes. An environment UUID is not interchangeable with a name in policy predicates.

Identity is more than a label

An application-supplied principal or customer ID is a claim. Bind credentials to an identity when policies or spend controls depend on it. Inventory labels do not prove who executed an action. See agents and identity.

Private deployments

Before login, set api_base_url to the installation’s deployment root and console_base_url to its customer console. For example:

kastra-edge config set api_base_url https://governance.example.com
kastra-edge config set console_base_url https://console.example.com
kastra-edge login

Replace these example hosts with the approved installation URLs. A reverse-proxy path prefix is supported; do not append an endpoint suffix such as /v1. admin_console_url is a separate operator destination and does not substitute for the customer console. Keep any custom configuration file private and use the same selection for hooks, MCP and CLI processes.