Environments

Environments in MITRITY provide logical isolation for your AI agent governance. Each environment — Development, Staging, Production, or any custom environment — operates as an independent governance context with its own agents, policies, audit logs, and API keys. This ensures that development experimentation does not affect production governance, and vice versa.

Overview

Environments are the primary organizational unit in MITRITY. When you create an agent or write a policy, you assign it to an environment. Resources in one environment are isolated from resources in another.

Tenant (Company)
├── Environment: Development
│   ├── Agents: dev-sales-bot, dev-data-bot
│   ├── Policies: allow-all-dev, deny-prod-resources
│   └── Audit Log: dev events only
├── Environment: Staging
│   ├── Agents: stg-sales-bot, stg-data-bot
│   ├── Policies: mirror of production policies
│   └── Audit Log: staging events only
└── Environment: Production
    ├── Agents: sales-bot, data-bot, support-bot
    ├── Policies: full governance policy set
    └── Audit Log: production events only

Resource Scoping

All major resources in MITRITY are scoped to an environment:

Resource	Scoped?	Description
Agents	Yes	Each agent belongs to exactly one environment
Policies	Yes	Policies are evaluated only within their environment
Audit events	Yes	Events are logged under the agent's environment
API keys	Yes or Tenant	Keys can be scoped to an environment or the entire tenant
Credentials	Yes or Tenant	Credentials can be scoped to an environment or available tenant-wide
Users	No	Users exist at the tenant level, with environment access governed by RBAC
Compliance reports	Yes	Reports are generated per environment

Cross-Environment Resources

Some resources intentionally span environments:

Users: A user's role and permissions apply across their assigned environments.
Threat intelligence: The threat feed applies globally — indicators are matched across all environments.
Tool catalog: Tool definitions are shared across environments (the tools themselves may be environment-specific, but their catalog definitions are global).
Settings: Global settings (MFA requirements, default permissions, notification channels) apply to all environments.

Managing Environments

Via the Dashboard

Navigate to Settings > Environments to view and manage environments.

Default Environment

Every tenant starts with a default "Production" environment. This environment cannot be deleted but can be renamed. At least one environment must exist at all times.

Creating an Environment

curl -X POST https://api.mitrity.com/api/v1/environments \
  -H "Authorization: Bearer mk_live_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Staging",
    "slug": "staging",
    "description": "Pre-production environment for testing policy changes and new agent deployments",
    "is_production": false
  }'

Response:

{
  "data": {
    "id": "env_staging",
    "name": "Staging",
    "slug": "staging",
    "description": "Pre-production environment for testing policy changes and new agent deployments",
    "is_production": false,
    "agent_count": 0,
    "policy_count": 0,
    "created_at": "2026-03-01T10:00:00Z",
    "updated_at": "2026-03-01T10:00:00Z"
  },
  "meta": {
    "request_id": "req_env001",
    "timestamp": "2026-03-01T10:00:00Z"
  }
}

Environment Fields

Field	Type	Required	Description
`name`	string	Yes	Display name (e.g., "Staging", "Development", "EU Production")
`slug`	string	Yes	URL-safe identifier (e.g., `staging`, `development`, `eu-production`). Must be unique within the tenant.
`description`	string	No	Description of the environment's purpose
`is_production`	boolean	No	Marks the environment as a production environment (default: `false`). See Production Flag.

Slug Naming Conventions

Slugs must follow these rules:

Lowercase letters, numbers, and hyphens only
Must start with a letter
Must be 3-50 characters long
Must be unique within the tenant

Recommended slugs:

Environment	Slug
Production	`production`
Staging	`staging`
Development	`development`
QA	`qa`
EU Production	`eu-production`
US Production	`us-production`
Load Testing	`load-testing`

Updating an Environment

curl -X PATCH https://api.mitrity.com/api/v1/environments/env_staging \
  -H "Authorization: Bearer mk_live_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Staging (EU)",
    "description": "Updated staging environment for EU region testing"
  }'

Deleting an Environment

curl -X DELETE https://api.mitrity.com/api/v1/environments/env_staging \
  -H "Authorization: Bearer mk_live_your-api-key"

Deletion rules:

The environment must have zero active agents.
Production-flagged environments cannot be deleted (remove the flag first).
Audit log data is retained for 90 days after environment deletion.
Policies, credentials, and grants scoped to the environment are deleted.

Listing Environments

curl https://api.mitrity.com/api/v1/environments \
  -H "Authorization: Bearer mk_live_your-api-key"

Response:

{
  "data": [
    {
      "id": "env_production",
      "name": "Production",
      "slug": "production",
      "description": "Production environment",
      "is_production": true,
      "agent_count": 5,
      "policy_count": 24,
      "created_at": "2026-01-15T10:00:00Z",
      "updated_at": "2026-02-28T14:00:00Z"
    },
    {
      "id": "env_staging",
      "name": "Staging",
      "slug": "staging",
      "description": "Pre-production environment",
      "is_production": false,
      "agent_count": 3,
      "policy_count": 24,
      "created_at": "2026-02-01T10:00:00Z",
      "updated_at": "2026-03-01T10:00:00Z"
    },
    {
      "id": "env_development",
      "name": "Development",
      "slug": "development",
      "description": "Development and testing",
      "is_production": false,
      "agent_count": 8,
      "policy_count": 5,
      "created_at": "2026-02-01T10:05:00Z",
      "updated_at": "2026-03-01T09:00:00Z"
    }
  ],
  "meta": {
    "request_id": "req_env002",
    "timestamp": "2026-03-01T10:10:00Z",
    "total": 3
  }
}

Production Flag

The is_production flag marks an environment as a production environment. Production environments receive additional protections:

Protection	Description
Deletion prevention	Production environments cannot be deleted until the flag is removed
Warning on policy changes	Policy modifications display a confirmation warning in the dashboard
Audit log retention	Production audit logs are retained for 1 year (vs 90 days for non-production)
Compliance report scope	Compliance reports default to production environment data

Setting the Production Flag

curl -X PATCH https://api.mitrity.com/api/v1/environments/env_production \
  -H "Authorization: Bearer mk_live_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "is_production": true
  }'

Removing the Production Flag

curl -X PATCH https://api.mitrity.com/api/v1/environments/env_production \
  -H "Authorization: Bearer mk_live_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "is_production": false
  }'

Removing the production flag requires Owner role and generates an audit log event.

Environment-Specific API Keys

API keys can be scoped to a specific environment. When using an environment-scoped key, all API requests are automatically filtered to that environment.

# Create an environment-scoped API key
curl -X POST https://api.mitrity.com/api/v1/api-keys \
  -H "Authorization: Bearer mk_live_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "staging-ci-key",
    "environment_id": "env_staging"
  }'

When using a staging-scoped key:

GET /api/v1/agents returns only staging agents
POST /api/v1/policies creates a policy in the staging environment
GET /api/v1/audit returns only staging audit events

See API Keys for more details.

Environment Strategies

Standard Three-Tier

The most common setup: Development, Staging, Production.

Environment	Enforcement Mode	Policy Set	Purpose
Development	Monitor	Minimal	Agent development and testing
Staging	Alert	Mirror of production	Pre-production validation
Production	Enforce	Full governance	Live agent governance

Regional Isolation

For organizations with regional compliance requirements:

Environment	Region	Description
EU Production	Europe	GDPR-compliant governance
US Production	Americas	SOC 2-compliant governance
APAC Production	Asia-Pacific	Regional compliance

Team-Based

For organizations with multiple teams operating independent agent fleets:

Environment	Team	Description
Sales Agents	Sales Engineering	Sales automation agents
Support Agents	Customer Support	Support automation agents
DevOps Agents	Platform Engineering	Infrastructure automation agents

Best Practices

Mirror Production Policies in Staging

Keep staging policies synchronized with production. Use policy simulations to validate changes in staging before applying to production.

Use Development for Experimentation

Keep development environments permissive (Monitor mode, minimal policies). This allows engineers to iterate quickly on agent development without governance friction.

Limit Production Environment Modifications

Restrict who can modify production environment configurations. Use scoped access to ensure only senior team members can make production changes.

Name Environments Clearly

Use descriptive names and slugs that make it obvious which environment a resource belongs to. Avoid ambiguous names like "Test" or "Env1."

Clean Up Unused Environments

Delete environments that are no longer in use. Dormant environments with stale policies and credentials can create confusion and security risks.