# Authentication and environments

Use the credential and environment contract for the surface you are connecting.

Updated: 2026-09-22

Canonical: https://docs.kastra.ai/start/authentication

## 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

```sh
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.

```sh
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](https://docs.kastra.ai/admin/agents).

## Private deployments

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

```sh
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.