# Workspaces, roles, and environments

Keep membership, policy scope, and environment identity explicit.

Updated: 2026-09-22

Canonical: https://docs.kastra.ai/admin/workspaces

## Select the workspace first

A user can belong to more than one workspace. Confirm the active workspace before managing policies, devices, keys, approvals, or evidence. A matching display name does not prove that an ID belongs to the intended workspace.

## Roles and approval permission

Console writes are protected by route-specific membership checks. ADMIN and OWNER perform administrative operations; approval permission can also be granted through `can_approve`. Some operations, such as a kill switch, have an OWNER requirement. Do not infer authority from a hidden or visible navigation item.

## Environment scope

Create environments to separate test and production policy. Display names aid navigation, while customer APIs generally use `environment_id` or `X-Environment-ID`. Policy predicates and some integration settings still use environment names. Check the endpoint contract before substituting a UUID for a name.

An API key is issued for an environment. An Edge device has a configured default environment. Validate these independently when the same user uses several workflows.

## Console visibility

The console adapts to the integrations and features a workspace uses. A hidden feature area does not prove that the backend lacks the feature or that policy is disabled. Check the actual configuration and entitlements.

## Verify an administrative change

Inspect the resulting workspace, membership, environment, and audit event. Test the intended permission with the appropriate credential. Keep the distinction between account identity, runtime principal claims, and agent inventory labels.