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:

Cross-Environment Resources

Some resources intentionally span environments:

• Users: A user's role applies across the organization. A user whose access scope is scoped works only in the environments granted to them, and sees only the agents granted to them, whichever environment those agents are in.
• 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 > General to view and manage environments. Owners and Managers create and update environments; only the Owner deletes one. Before you confirm a deletion, the confirmation says what it removes (the environment's agents and their data, its API keys, policies and report schedules, and users' access to it) and what it keeps: how many of the environment's compliance reports in the reports list are kept, and how many active share links they have.

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_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 (201 Created):

{
  "id": "env_staging",
  "tenant_id": "tnt_4f9a",
  "name": "Staging",
  "slug": "staging",
  "description": "Pre-production environment for testing policy changes and new agent deployments",
  "is_production": false,
  "created_at": "2026-03-01T10:00:00Z",
  "updated_at": "2026-03-01T10:00:00Z"
}

Owners and Managers create environments, up to your plan's environment limit.

Environment Fields

Slug Naming Conventions

Slugs must follow these rules:

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

Recommended slugs:

Updating an Environment

curl -X PUT https://api.mitrity.com/api/v1/environments/env_staging \
  -H "Authorization: Bearer mk_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_your-api-key"

Deletion rules:

• Only the Owner can delete an environment, and not with an API key bound to an environment, the environment's own key included (403).
• A production-flagged environment cannot be deleted (400).
• Deleting an environment also deletes what works in it: its agents and their data, its API keys, its policies with their versions, rules, DLP bindings and budgets, its report schedules, and users' access to it. This cannot be undone. The dashboard's delete confirmation says the same before you confirm.
• Its compliance reports are kept, with their evidence and share links, and become organization reports: they are no longer filed under an environment (environment_id is null). Reports its schedules produced are kept the same way.
• Its red-team campaigns are kept, with their runs and findings, and no longer belong to an environment. A campaign that was active is paused, so it does not start running across the organization, and every run still queued or running ends as aborted with campaign_paused. A campaign runs only while it has an environment: give it one and resume it if it should keep running.
• A SIEM destination is kept and keeps forwarding.
• Audit events are kept, and still name the environment they happened in.
• The deletion is recorded on the audit trail as environment.deleted, with what was removed, what was kept (the reports and SIEM destinations it kept are listed by id), which campaigns were paused and which runs were ended (aborted_run_ids).

What a Deletion Keeps

The dashboard's delete confirmation says what the deletion keeps before you confirm it, for example "Its 3 compliance reports are kept, with 2 active share links." It counts the reports in your reports list. The same counts are available from the API:

curl https://api.mitrity.com/api/v1/environments/env_staging/deletion-preview \
  -H "Authorization: Bearer mk_your-api-key"

Response (200 OK):

{
  "reports_kept": 4,
  "reports_listed": 3,
  "live_share_links": 2
}

• reports_kept counts every compliance report the deletion keeps, including reports deleted from the reports list: their records are kept too.
• reports_listed counts only the reports still in the reports list. This is the number the confirmation shows, and it is never more than reports_kept.
• live_share_links counts the share links on those reports that still open: not revoked, not expired, under their view limit, and on a report that is ready and not deleted. They keep working after the deletion until they expire or are revoked.
• reports_kept and live_share_links are counted the way the deletion counts what it keeps, so the environment.deleted audit event records the same numbers unless reports or share links change in between.
• Reading the preview changes nothing. It answers only those who may delete the environment, with the same 403, 404 and 400 answers the deletion gives.

Listing Environments

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

The list holds the environments you have access to: every environment for an Owner or a user whose access scope is all, and only the granted ones for a scoped user. Any other environment answers 404 Not Found.

Response:

{
  "environments": [
    {
      "id": "env_production",
      "tenant_id": "tnt_4f9a",
      "name": "Production",
      "slug": "production",
      "description": "Production environment",
      "is_production": true,
      "created_at": "2026-01-15T10:00:00Z",
      "updated_at": "2026-02-28T14:00:00Z"
    },
    {
      "id": "env_staging",
      "tenant_id": "tnt_4f9a",
      "name": "Staging",
      "slug": "staging",
      "description": "Pre-production environment",
      "is_production": false,
      "created_at": "2026-02-01T10:00:00Z",
      "updated_at": "2026-03-01T10:00:00Z"
    }
  ]
}

Production Flag

The is_production flag marks an environment as a production environment. It does two things:

The flag changes nothing else:

• Audit log retention follows your plan in every environment: 7 days on Starter, 30 days on Pro and 90 days on Enterprise.
• Policy changes in a production environment are saved like any other, without an extra confirmation step.
• A compliance report filed under a production environment covers what any other report covers. Every report is filed under the environment it is generated in: the one you pick in the dashboard's environment switcher, or the environment_id you send to the API. Its figures still cover every environment of your organization, and an AI assessment covers the one agent it is about. See Read the scope line.

Setting the Production Flag

The flag is set when the environment is created and stays as created: updating an environment changes only its name and description. Create a production environment with "is_production": true:

curl -X POST https://api.mitrity.com/api/v1/environments \
  -H "Authorization: Bearer mk_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "EU Production",
    "slug": "eu-production",
    "is_production": true
  }'

Environment-Specific API Keys

API keys can be scoped to a specific environment. An environment-scoped key works in that environment only: lists are filtered to it, a resource of another environment answers 404 Not Found, and a create that names no environment lands in the key's.

# Create an environment-scoped API key
curl -X POST https://api.mitrity.com/api/v1/api-keys \
  -H "Authorization: Bearer mk_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, and naming another environment is refused with 403 Forbidden
• GET /api/v1/audit returns only the audit events of staging agents
• Actions that belong to the whole organization, such as an organization-wide report or connecting a SaaS platform, are refused with 403 Forbidden
• Actions that only an Owner may take, such as changing the organization's settings, billing, removing users or deleting an environment, are refused with 403 Forbidden, even when an Owner created the key

See API Keys for more details.

Environment Strategies

Standard Three-Tier

The most common setup: Development, Staging, Production.

Regional Isolation

For organizations with regional compliance requirements:

Team-Based

For organizations with multiple teams operating independent agent fleets:

Best Practices

Mirror Production Policies in Staging

Keep staging policies synchronized with production. Roll new policies through staging first to validate behavior on real (or representative) traffic 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 change production. Scope your team, give access to the production environment only to the people who maintain its policies, and grant production agents only to the people who look after them.

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.

Related Documentation

• RBAC — Roles, access scope and environment access
• API Keys — Environment-scoped API keys
• SAML SSO — Enterprise SSO configuration
• Compliance Reports — Generating reports, and what their figures cover