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 full lifecycle audit trailing.

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}

Component	Description	Example
`mk_`	Prefix identifying a MITRITY API key	`mk_`
`{64-character-hex}`	Random 64-character hexadecimal string	`a1b2c3d4e5f6...`

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 (prefixed with mk_) have access to resources across all environments. The environment is specified per request using query parameters or request bodies.

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

Environment-Scoped Keys

Environment-scoped keys restrict all API operations to a single environment. When using a scoped key:

List endpoints return only resources in that environment
Create endpoints assign new resources to that environment
Attempting to access resources in other environments returns 403 Forbidden

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:

Part	Values
`resource`	An API path segment (e.g. `policies`, `agents`, `credentials`) or `*` for all resources
`action`	`read`, `write`, or `*`

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

Navigate to Settings > API Keys.
Click Create API Key.
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
- Scope: Tenant-wide or a specific environment
- Expiration: Optional expiration date (recommended for security)
Click Create.
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:

{
  "data": {
    "id": "key_8k2m4n",
    "name": "CI/CD Pipeline - Staging",
    "key": "mk_a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef12",
    "prefix": "mk_a1b2c3d4",
    "environment_id": "env_staging",
    "environment_name": "Staging",
    "status": "active",
    "expires_at": "2026-06-01T00:00:00Z",
    "created_by": "user_jsmith",
    "created_at": "2026-03-01T10:00:00Z"
  },
  "meta": {
    "request_id": "req_key001",
    "timestamp": "2026-03-01T10:00:00Z"
  }
}

Important: The full key value is only returned in the creation response. After this, only the prefix (first 16 characters) is stored for identification purposes.

Key Fields

Field	Type	Required	Description
`name`	string	Yes	Descriptive name for the key
`environment_id`	string	No	Scope to a specific environment. Omit for tenant-wide.
`scopes`	string[]	No	Least-privilege access scopes (e.g. `["*:read"]` for read-only). Omit for unrestricted (role-only).
`expires_at`	datetime	No	Expiration timestamp (ISO 8601). Omit for non-expiring keys.

Key Lifecycle

Statuses

Status	Description
`active`	Key is valid and can be used for API requests
`expired`	Key has passed its expiration date. Cannot be used.
`revoked`	Key has been manually revoked. Cannot be used.

Active Keys

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

Expired Keys

When a key reaches its expires_at timestamp, it transitions to expired status. API requests using an expired key receive a 401 Unauthorized response:

{
  "error": {
    "code": "api_key_expired",
    "message": "This API key expired on 2026-06-01T00:00:00Z. Create a new key in Settings > API Keys.",
    "request_id": "req_xyz789"
  }
}

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",
      "name": "CI/CD Pipeline - Staging",
      "prefix": "mk_a1b2c3d4",
      "environment_id": "env_staging",
      "environment_name": "Staging",
      "status": "active",
      "expires_at": "2026-06-01T00:00:00Z",
      "last_used_at": "2026-03-01T09:45:00Z",
      "created_by": "user_jsmith",
      "created_at": "2026-03-01T10:00:00Z"
    },
    {
      "id": "key_9j3n5p",
      "name": "Production Monitoring",
      "prefix": "mk_b2c3d4e5",
      "environment_id": null,
      "environment_name": null,
      "status": "active",
      "expires_at": null,
      "last_used_at": "2026-03-01T10:02:00Z",
      "created_by": "user_jsmith",
      "created_at": "2026-02-15T10:00:00Z"
    }
  ],
  "meta": {
    "request_id": "req_key002",
    "timestamp": "2026-03-01T10:05:00Z",
    "total": 2
  }
}

List Filters

Parameter	Type	Description
`status`	enum	Filter by status: `active`, `expired`, `revoked`
`environment_id`	string	Filter by environment scope
`limit`	integer	Results per page (default: 25, max: 100)

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 \
  -H "Authorization: Bearer mk_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "environment_id": "env_production"
  }'

Response:

{
  "data": {
    "id": "key_8k2m4n",
    "name": "CI/CD Pipeline - Staging",
    "prefix": "mk_a1b2c3d4",
    "environment_id": "env_production",
    "environment_name": "Production",
    "status": "active",
    "updated_at": "2026-03-01T11:00:00Z"
  },
  "meta": {
    "request_id": "req_key003",
    "timestamp": "2026-03-01T11:00:00Z"
  }
}

Note: Changing the scope updates the logical scope but does not change the key prefix in the key string itself. The prefix is set at creation time.

Revoking API Keys

Revoke a key to immediately invalidate it:

curl -X POST https://api.mitrity.com/api/v1/api-keys/key_8k2m4n/revoke \
  -H "Authorization: Bearer mk_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Key rotation: replacing with new key"
  }'

Response:

{
  "data": {
    "id": "key_8k2m4n",
    "name": "CI/CD Pipeline - Staging",
    "status": "revoked",
    "revoked_by": "user_jsmith",
    "revoked_reason": "Key rotation: replacing with new key",
    "revoked_at": "2026-03-01T12:00:00Z"
  },
  "meta": {
    "request_id": "req_key004",
    "timestamp": "2026-03-01T12:00:00Z"
  }
}

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

Key Rotation

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

Rotation Process

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

Zero-Downtime Rotation

To rotate without downtime:

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

Rotation Reminders

MITRITY sends notifications when keys are approaching 90 days old (or any custom rotation interval configured in Settings > Security > API Key Rotation):

14 days before: Warning notification via Slack/email
7 days before: Reminder notification
On expiration: Alert notification (if the key has an expiration date)

Dashboard: Settings > API Keys

The API Keys tab in the dashboard provides:

Key list: All keys with name, prefix, scope, status, last used, and age
Usage metrics: Request count per key over the last 30 days
Key creation: Visual key creation flow with scope selection
Revocation: One-click key revocation with reason prompt
Rotation status: Visual indicator of keys due for rotation

Audit Trail

All API key operations are logged in the audit log:

Event	Description
`api_key.created`	New API key created
`api_key.used`	API key used for authentication (logged periodically, not per-request)
`api_key.scope_updated`	Key environment scope changed
`api_key.revoked`	Key revoked
`api_key.expired`	Key expired

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

API keys inherit the permissions of the user who created them
When a user is removed from the tenant, all keys created by that user are automatically revoked
Keys cannot exceed the permissions of their creator's role

Rate Limiting

API keys are subject to the same rate limits as interactive sessions. Rate limits apply per key, not per user.

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. Set rotation reminders to avoid expired keys disrupting automation.

Monitor Last Used Dates

Review the "last used" timestamp regularly. 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.

API Keys

Overview

Key Format

Environment Scoping

Tenant-Wide Keys

Environment-Scoped Keys

Access Level (Least-Privilege)

Scope format

Creating a read-only key

Creating API Keys

Via the Dashboard

Via the API

Key Fields

Key Lifecycle

Statuses

Active Keys

Expired Keys

Revoked Keys

Listing API Keys

List Filters

Updating API Key Scope

Revoking API Keys

Key Rotation

Rotation Process

Zero-Downtime Rotation

Rotation Reminders

Dashboard: Settings > API Keys

Audit Trail

Security Considerations

Key Storage

Key Permissions

Rate Limiting

Best Practices

Use Environment-Scoped Keys

Set Expiration Dates

Use Descriptive Names

Rotate Every 90 Days

Monitor Last Used Dates

Limit Key Count

Related Documentation