API Keys

API keys provide programmatic access to the MITRITY REST API. They are used by CI/CD pipelines, automation scripts, custom integrations, and SDKs to authenticate requests without interactive login. MITRITY's API key system supports environment scoping, key rotation, and an audit trail of every key created, revoked or moved to another environment.

Overview

Every API request to MITRITY requires authentication. While interactive users authenticate via session tokens (from email/password, Google SSO, or SAML), programmatic access uses API keys sent as Bearer tokens:

curl https://api.mitrity.com/api/v1/agents \
  -H "Authorization: Bearer mk_a1b2c3d4e5f6..."

Key Format

MITRITY API keys have a fixed format:

mk_{64-character-hex}

The key string itself does not encode the environment or access level — both environment scope and access scopes are stored as metadata on the key, not in the string. The first 8 characters (mk_ + 5 hex) are kept as a non-secret prefix to identify the key in lists and audit logs.

Example: mk_a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef1234

Environment Scoping

API keys can be tenant-wide or scoped to a specific environment.

Tenant-Wide Keys

Tenant-wide keys have access to resources across every environment their creator can reach. The environment is specified per request using query parameters or request bodies.

Only an Owner, or a user whose access scope is all, can create a tenant-wide key or make an existing key tenant-wide. Anyone else gets 403 Forbidden and binds their keys to an environment they work in.

Use case: CI/CD pipelines that need to operate across multiple environments.

Environment-Scoped Keys

An environment-scoped key works in its own environment and nowhere else, whoever created it. When using a scoped key:

• Lists return only what belongs to that environment: its agents, its policies, and the records about its agents. When the key's creator is scoped, the key sees only the part of that environment the creator can see.
• A single resource of another environment answers 404 Not Found, the answer an unknown ID gets.
• A create that names no environment is placed in the key's environment. A create that names another environment is refused with 403 Forbidden. This applies to agents, policies, reports, report schedules and red-team campaigns.
• Actions that belong to the whole organization are refused with 403 Forbidden, as they are for a scoped user. These are organization-wide reports, the usage of governed actions, connecting or changing a SaaS platform, and creating, changing or deleting a credential.
• The key cannot change which environment any key is bound to, its own included (403 Forbidden). It creates only keys bound to its own environment: a request for another environment, or for a tenant-wide key, is refused with 403 Forbidden.
• The key takes no action that only an Owner may take, even when an Owner created it (403 Forbidden). It cannot make anyone an Owner, by invitation or by a role change, or change an Owner's role, profile, MFA or access; remove a user; reset a Manager's MFA; change the organization's settings or SAML SSO; open billing or change the plan; delete an environment, its own included, or the organization; change the governance gate or the assessment templates; resolve a review assigned to Owners; approve an agent directly; or publish, retire or delete an AI policy statement. Below that line, a key created by an Owner does what a Manager's key could, in its environment.
• If the key's binding cannot be read, the key is refused rather than widened.

Use case: Dedicated keys for each environment in a multi-environment setup.

Access Level (Least-Privilege)

Independently of environment scope, a key can be restricted to a least-privilege access level using scopes. Scopes are enforced at the API auth layer, on top of the creating user's role — a key can only ever narrow what its creator could do, never widen it.

• Full access (default — no scopes): the key may read and write, up to the role of the user who created it.
• Read-only (scopes: ["*:read"]): the key may perform every GET and is denied every mutating request (POST / PUT / PATCH / DELETE) with a 403, regardless of the creator's role.
• Custom (per-resource scopes): grant read-only or read & write on a chosen set of resources, leaving every other resource denied. In the dashboard, pick Custom in the access-level selector and set each resource to None, Read, or Read & write. Each selection becomes a <resource>:<action> scope — Read → <resource>:read, Read & write → <resource>:* — and a live preview shows the exact scope strings (e.g. agents:*, policies:read).

Read-only keys are ideal for dashboards, reporting integrations, and anything that should never change platform state. Custom keys are ideal for narrowly-scoped integrations that only touch a few resources.

Scope format

Scopes are an array of "<resource>:<action>" strings:

A bare "*" is shorthand for full access (same as no scopes). A key with no scopes is unrestricted (role-only).

Creating a read-only key

In the dashboard, pick Read-only in the access-level selector when creating the key. Via the API, pass scopes:

curl -X POST https://api.mitrity.com/api/v1/api-keys \
  -H "Authorization: Bearer mk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Reporting integration (read-only)",
    "scopes": ["*:read"]
  }'

A write attempted with a read-only key returns:

{ "error": "API key scope does not permit this operation", "code": 403 }

Creating API Keys

Via the Dashboard

1. Navigate to Settings > API Keys.
2. Click Create API Key.
3. Fill in the key details:
   • Name: A descriptive name (e.g., CI/CD Pipeline - Staging)
   • Access level: Full access, Read-only, or Custom per-resource read/write scopes
   • Environment: All environments (tenant-wide) or one environment. A scoped user picks one of the environments they work in.
   • Expiration: Optional expiration date (recommended for security)
4. Click Create.
5. Copy the key immediately — it is only shown once. After closing the dialog, the key value cannot be retrieved.

Via the API

curl -X POST https://api.mitrity.com/api/v1/api-keys \
  -H "Authorization: Bearer mk_your-existing-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline - Staging",
    "environment_id": "env_staging",
    "expires_at": "2026-06-01T00:00:00Z"
  }'

Response (201 Created):

{
  "id": "key_8k2m4n",
  "tenant_id": "tnt_4f9a",
  "created_by": "user_jsmith",
  "name": "CI/CD Pipeline - Staging",
  "key_prefix": "mk_a1b2c",
  "scopes": [],
  "expires_at": "2026-06-01T00:00:00Z",
  "created_at": "2026-03-01T10:00:00Z",
  "environment_id": "env_staging",
  "raw_key": "mk_a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef1234"
}

Important: The full key (raw_key) is only returned in the creation response. MITRITY stores a hash of it; afterwards only the key_prefix (the first 8 characters) identifies the key.

Key Fields

Key Lifecycle

States

A key's state follows from its timestamps:

Active Keys

Active keys authenticate API requests normally. The key remains active until it expires or is revoked.

Expired Keys

Once a key passes its expires_at timestamp, requests using it receive 401 Unauthorized — the same response as an unknown or revoked key, so the response does not reveal which keys exist:

{ "error": "invalid API key", "code": 401 }

Revoked Keys

Revoked keys are permanently invalidated. Revocation is immediate — any in-flight requests using the key will fail.

Listing API Keys

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

Response:

{
  "data": [
    {
      "id": "key_8k2m4n",
      "tenant_id": "tnt_4f9a",
      "created_by": "user_jsmith",
      "name": "CI/CD Pipeline - Staging",
      "key_prefix": "mk_a1b2c",
      "scopes": [],
      "expires_at": "2026-06-01T00:00:00Z",
      "last_used_at": "2026-03-01T09:45:00Z",
      "created_at": "2026-03-01T10:00:00Z",
      "environment_id": "env_staging"
    },
    {
      "id": "key_9j3n5p",
      "tenant_id": "tnt_4f9a",
      "created_by": "user_jsmith",
      "name": "Production Monitoring",
      "key_prefix": "mk_b2c3d",
      "scopes": ["*:read"],
      "last_used_at": "2026-03-01T10:02:00Z",
      "created_at": "2026-02-15T10:00:00Z"
    }
  ],
  "total": 2,
  "limit": 50,
  "offset": 0
}

Revoked keys stay in the list with revoked_at set. A field without a value (expires_at, last_used_at, revoked_at, environment_id) is left out of the key.

Who Sees and Manages Which Keys

total counts the same keys the list shows.

Pagination

Updating API Key Scope

Change the environment scope of an existing key:

curl -X PATCH https://api.mitrity.com/api/v1/api-keys/key_8k2m4n/environment \
  -H "Authorization: Bearer mk_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "environment_id": "env_production"
  }'

Send "environment_id": null to make the key tenant-wide again, which takes full access: an Owner, or a user whose access scope is all (403 otherwise). A scoped user binds a key only to an environment they work in; any other environment answers 404. A revoked key cannot be changed (400), and viewers cannot change keys (403). A member changes only the keys they created, and a request made with an environment-scoped key cannot change the environment of any key (403).

Response: the updated key, in the same shape as the list returns it:

{
  "id": "key_8k2m4n",
  "tenant_id": "tnt_4f9a",
  "created_by": "user_jsmith",
  "name": "CI/CD Pipeline - Staging",
  "key_prefix": "mk_a1b2c",
  "scopes": [],
  "expires_at": "2026-06-01T00:00:00Z",
  "last_used_at": "2026-03-01T09:45:00Z",
  "created_at": "2026-03-01T10:00:00Z",
  "environment_id": "env_production"
}

Note: Changing the scope changes the key's metadata, not the key string: the key keeps working with its new scope, and its prefix stays the same.

Revoking API Keys

Revoke a key to immediately invalidate it:

curl -X DELETE https://api.mitrity.com/api/v1/api-keys/key_8k2m4n \
  -H "Authorization: Bearer mk_your-api-key"

Response: the key with revoked_at set:

{
  "id": "key_8k2m4n",
  "tenant_id": "tnt_4f9a",
  "created_by": "user_jsmith",
  "name": "CI/CD Pipeline - Staging",
  "key_prefix": "mk_a1b2c",
  "scopes": [],
  "expires_at": "2026-06-01T00:00:00Z",
  "last_used_at": "2026-03-01T09:45:00Z",
  "revoked_at": "2026-03-01T12:00:00Z",
  "created_at": "2026-03-01T10:00:00Z",
  "environment_id": "env_production"
}

Revocation is permanent. Revoked keys cannot be reactivated. Create a new key if needed.

Owners and Managers revoke any key. A member revokes only the keys they created, and viewers cannot revoke keys (403).

Key Rotation

Regular key rotation limits the impact of a compromised key. MITRITY recommends rotating API keys every 90 days.

Rotation Process

1. Create a new key with the same scope and permissions as the old key.
2. Update your applications to use the new key.
3. Verify the new key works by running a test API call.
4. Revoke the old key once all applications have been updated.

Zero-Downtime Rotation

To rotate without downtime:

1. Create the new key.
2. Deploy the new key to your applications alongside the old key (both are valid simultaneously).
3. Once all applications are using the new key, revoke the old key.

Keeping Track of Keys

MITRITY does not remind you to rotate keys. To keep rotation on schedule:

• Set expires_at when you create a key, for example 90 days out. An expired key stops working on its own, so a forgotten key cannot live on.
• Review last_used_at, which GET /api/v1/api-keys returns for every key that has been used. It is updated on each request the key makes.
• Revoke keys you no longer use. A key that has not been used in 30 days may be orphaned.

Dashboard: Settings > API Keys

The API Keys tab in the dashboard provides:

• Key list: The keys you can see, with name, prefix, access level, environment, creation date and status. A key past its expiration date shows as Expired, with how long ago it expired. Revoked keys are listed apart, with the date they were revoked.
• Key creation: Name, access level, environment and an optional expiration date. The key is shown once.
• Environment: Change the environment a key is bound to from the list.
• Revocation: Revoke a key after a confirmation step.

Audit Trail

Creating a key, revoking it and changing its environment are recorded on your organization's audit trail as governance changes:

Each entry names the person who made the change, and the API key they made it with, if any. The key itself and its hash are never recorded, and a refused request writes nothing.

Using a key writes no entry: each key's last_used_at shows when it was last used. A key reaching its expiration date writes none either; from then on it is refused, and the API Keys tab shows it as Expired.

In the Audit Log, pick the source Governance Changes: each entry shows its event type, with the key's prefix beneath. Through the API:

curl "https://api.mitrity.com/api/v1/audit?source=control_plane&event_type=api_key.created" \
  -H "Authorization: Bearer mk_your-api-key"

These entries, like every change to people and their access, are shown to Owners and Managers only; Members and Viewers do not see them in the audit log. A key belongs to no agent, so they are not shown to a user whose access scope is scoped either, nor to a request made with an environment-scoped key.

Security Considerations

Key Storage

• Never commit API keys to source control (use .env files or secret managers)
• Never expose keys in client-side code (browser JavaScript)
• Use environment variables or secret management services (GCP Secret Manager, AWS Secrets Manager, HashiCorp Vault)

Key Permissions

• An API key acts with the current role and access scope of the user who created it: a key made by a scoped user sees only the agents and environments granted to that user, and a change to the user's role, access scope, agent grants or environment access applies to the key at once
• When a user is removed from the tenant, all keys created by that user are deleted and stop working at once
• Keys cannot exceed the permissions of their creator's role

Rate Limiting

All of your tenant's API keys share one rate limit of 100 requests a minute. Dashboard sessions are counted separately, per person, so people using the dashboard do not spend your integrations' budget.

Best Practices

Use Environment-Scoped Keys

Create separate keys for each environment. A staging CI/CD pipeline should not use a production-scoped key.

Set Expiration Dates

Always set expiration dates on API keys. Non-expiring keys that are forgotten about become security liabilities.

Use Descriptive Names

Name keys by their purpose and environment: "CI/CD Pipeline - Staging" is better than "API Key 1."

Rotate Every 90 Days

Follow a 90-day rotation schedule. Give each key an expiration date that matches it, and replace the key before that date so automation keeps working.

Monitor Last Used Dates

Review each key's last_used_at regularly through the API. Keys that have not been used in 30 days may be orphaned and should be revoked.

Limit Key Count

Create the minimum number of keys necessary. Each active key is a potential attack surface. Consolidate where possible.

Related Documentation

• API Overview — Authentication, rate limits, and endpoint reference
• RBAC — Role-based permissions (keys inherit user permissions)
• Environments — Environment scoping for API keys
• SAML SSO — Interactive authentication (complementary to API keys)
• Billing — Plans and what they include