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_live_a1b2c3d4e5f6..."

Key Format

MITRITY API keys follow a structured format for easy identification:

mk_{environment}_{64-character-hex}

Component	Description	Example
`mk_`	Prefix identifying a MITRITY API key	`mk_`
`{environment}`	The environment scope (or `live` for tenant-wide)	`live`, `staging`, `dev`
`{64-character-hex}`	Random 64-character hexadecimal string	`a1b2c3d4e5f6...`

Examples:

Tenant-wide key: mk_live_a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef12
Staging-scoped key: mk_staging_b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef1234
Development-scoped key: mk_dev_c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456

Environment Scoping

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

Tenant-Wide Keys

Tenant-wide keys (prefixed with mk_live_) 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.

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)
- 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_live_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_staging_a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef12",
    "prefix": "mk_staging_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.
`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_live_your-api-key"

Response:

{
  "data": [
    {
      "id": "key_8k2m4n",
      "name": "CI/CD Pipeline - Staging",
      "prefix": "mk_staging_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_live_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_live_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_staging_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_live_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

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