Credential Broker

AI agents need credentials to access external services — API keys, OAuth tokens, database passwords, and service account keys. Without governance, agents often receive long-lived credentials with overly broad access, creating significant security risk. MITRITY's credential broker provides a secure, audited, and time-limited way to grant agents access to credentials.

Overview

The credential broker operates as an intermediary between your credential store and your agents. Instead of directly embedding credentials in agent configurations, you:

Define credentials in the MITRITY credential vault (encrypted, tenant-isolated)
Create grants specifying which agents can access which credentials
Issue leases — time-bound, revocable access tokens that agents use to retrieve the actual credential
Audit everything — every credential access, lease creation, and revocation is logged

Agent ──lease request──► Gateway ──validate──► Credential Broker
                                                       │
                                               ┌───────┼───────┐
                                               │   Check grant  │
                                               │   Create lease │
                                               │   Return cred  │
                                               └───────┬───────┘
                                                       │
                                              credential (time-bound)
                                                       │
Agent ◄────────────────────────────────────────────────┘

Credential Types

The broker supports four credential types:

Type	Description	Examples
`api_key`	API keys and tokens for external services	OpenAI API key, Stripe secret key, SendGrid API key
`oauth_token`	OAuth 2.0 access tokens and refresh tokens	Google OAuth token, GitHub OAuth token, Salesforce token
`db_password`	Database connection passwords	PostgreSQL password, MongoDB credentials, Redis password
`service_account`	Cloud service account credentials	GCP service account JSON, AWS IAM credentials

Defining Credentials

Via the Dashboard

Navigate to Security > Credential Broker.
Click Add Credential.
Fill in the credential details:
- Name: Human-readable identifier (e.g., openai-production-key)
- Type: Select the credential type
- Value: The actual credential (encrypted at rest)
- Description: Purpose and context
- Rotation schedule: Optional automatic rotation reminder
Click Save.

Via the API

curl -X POST https://api.mitrity.com/api/v1/credentials \
  -H "Authorization: Bearer mk_live_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "openai-production-key",
    "type": "api_key",
    "value": "sk-proj-abc123...",
    "description": "OpenAI API key for production agent LLM calls",
    "environment_id": "env_production",
    "metadata": {
      "provider": "openai",
      "tier": "tier-4",
      "rotation_interval_days": 90
    }
  }'

Response:

{
  "data": {
    "id": "cred_8k2m4n",
    "name": "openai-production-key",
    "type": "api_key",
    "description": "OpenAI API key for production agent LLM calls",
    "environment_id": "env_production",
    "metadata": {
      "provider": "openai",
      "tier": "tier-4",
      "rotation_interval_days": 90
    },
    "created_at": "2026-03-01T10:00:00Z",
    "updated_at": "2026-03-01T10:00:00Z",
    "last_rotated_at": "2026-03-01T10:00:00Z",
    "active_leases": 0,
    "total_grants": 0
  },
  "meta": {
    "request_id": "req_cred001",
    "timestamp": "2026-03-01T10:00:00Z"
  }
}

The credential value is never returned in API responses after creation. It is encrypted at rest using AES-256-GCM and stored in the tenant's isolated credential vault.

Credential Fields

Field	Type	Required	Description
`name`	string	Yes	Unique name within the tenant (e.g., `openai-prod`)
`type`	enum	Yes	One of: `api_key`, `oauth_token`, `db_password`, `service_account`
`value`	string	Yes	The actual credential value (encrypted at rest)
`description`	string	No	Human-readable description
`environment_id`	string	No	Scope to a specific environment
`metadata`	object	No	Arbitrary metadata (provider, tier, rotation schedule, etc.)

Grants

A grant authorizes a specific agent to access a specific credential. Without a grant, an agent cannot request a lease for a credential, even if the agent has broad tool permissions.

Creating a Grant

curl -X POST https://api.mitrity.com/api/v1/credentials/cred_8k2m4n/grants \
  -H "Authorization: Bearer mk_live_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_llm-bot",
    "max_lease_ttl_minutes": 60,
    "max_concurrent_leases": 3,
    "allowed_operations": ["read"],
    "conditions": {
      "require_justification": true,
      "allowed_time_window": {
        "days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
        "start": "08:00",
        "end": "20:00",
        "timezone": "Europe/Stockholm"
      }
    }
  }'

Response:

{
  "data": {
    "id": "grant_9j3n5p",
    "credential_id": "cred_8k2m4n",
    "credential_name": "openai-production-key",
    "agent_id": "agt_llm-bot",
    "agent_name": "llm-bot",
    "max_lease_ttl_minutes": 60,
    "max_concurrent_leases": 3,
    "allowed_operations": ["read"],
    "conditions": {
      "require_justification": true,
      "allowed_time_window": {
        "days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
        "start": "08:00",
        "end": "20:00",
        "timezone": "Europe/Stockholm"
      }
    },
    "active": true,
    "created_at": "2026-03-01T10:05:00Z"
  },
  "meta": {
    "request_id": "req_grant001",
    "timestamp": "2026-03-01T10:05:00Z"
  }
}

Grant Fields

Field	Type	Required	Description
`agent_id`	string	Yes	The agent authorized to access the credential
`max_lease_ttl_minutes`	integer	Yes	Maximum lease duration in minutes (1-1440)
`max_concurrent_leases`	integer	Yes	Maximum active leases at the same time (1-100)
`allowed_operations`	array	No	Operations the agent can perform (default: `["read"]`)
`conditions`	object	No	Additional conditions for the grant
`conditions.require_justification`	boolean	No	Require the agent to provide a justification when requesting a lease
`conditions.allowed_time_window`	object	No	Restrict lease creation to specific time windows

Listing Grants for a Credential

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

Revoking a Grant

When a grant is revoked, all active leases for that grant are also revoked immediately:

curl -X DELETE https://api.mitrity.com/api/v1/credentials/cred_8k2m4n/grants/grant_9j3n5p \
  -H "Authorization: Bearer mk_live_your-api-key"

Leases

A lease is a time-bound access token that an agent uses to retrieve the actual credential value. Leases are the core mechanism for providing just-in-time credential access.

Lease Lifecycle

Request ──► Created (active) ──► Expired (TTL elapsed)
                │
                ├──► Revoked (manually or cascading)
                │
                └──► Renewed (TTL extended)

Status	Description
`active`	The lease is valid and the agent can use it to access the credential
`expired`	The lease TTL has elapsed. The agent must request a new lease.
`revoked`	The lease was manually revoked or revoked due to a cascading revocation

Creating a Lease

Agents request leases through the gateway. The gateway validates the grant and creates the lease:

curl -X POST https://api.mitrity.com/api/v1/credentials/cred_8k2m4n/leases \
  -H "Authorization: Bearer mk_live_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_llm-bot",
    "ttl_minutes": 30,
    "justification": "Processing customer support ticket #4521"
  }'

Response:

{
  "data": {
    "id": "lease_7p4q2r",
    "credential_id": "cred_8k2m4n",
    "credential_name": "openai-production-key",
    "agent_id": "agt_llm-bot",
    "credential_value": "sk-proj-abc123...",
    "status": "active",
    "ttl_minutes": 30,
    "justification": "Processing customer support ticket #4521",
    "expires_at": "2026-03-01T10:35:00Z",
    "created_at": "2026-03-01T10:05:00Z"
  },
  "meta": {
    "request_id": "req_lease001",
    "timestamp": "2026-03-01T10:05:00Z"
  }
}

The credential value is returned only in the lease creation response. Subsequent queries to the lease endpoint do not return the value.

Lease Fields

Field	Type	Required	Description
`agent_id`	string	Yes	The agent requesting the lease
`ttl_minutes`	integer	Yes	Lease duration in minutes (must be <= grant's `max_lease_ttl_minutes`)
`justification`	string	Conditional	Required if the grant has `require_justification: true`

Renewing a Lease

Extend an active lease before it expires:

curl -X POST https://api.mitrity.com/api/v1/credentials/cred_8k2m4n/leases/lease_7p4q2r/renew \
  -H "Authorization: Bearer mk_live_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "ttl_minutes": 30
  }'

Renewal extends the expiration time. The total active time cannot exceed the grant's max_lease_ttl_minutes multiplied by 2 (prevents indefinite renewal).

Listing Active Leases

curl "https://api.mitrity.com/api/v1/credentials/cred_8k2m4n/leases?status=active" \
  -H "Authorization: Bearer mk_live_your-api-key"

Response:

{
  "data": [
    {
      "id": "lease_7p4q2r",
      "credential_id": "cred_8k2m4n",
      "agent_id": "agt_llm-bot",
      "agent_name": "llm-bot",
      "status": "active",
      "ttl_minutes": 30,
      "justification": "Processing customer support ticket #4521",
      "expires_at": "2026-03-01T10:35:00Z",
      "created_at": "2026-03-01T10:05:00Z"
    }
  ],
  "meta": {
    "request_id": "req_lease002",
    "timestamp": "2026-03-01T10:10:00Z",
    "next_cursor": null,
    "total": 1
  }
}

Revocation

Revoking a Single Lease

Immediately invalidate a specific lease:

curl -X POST https://api.mitrity.com/api/v1/credentials/cred_8k2m4n/leases/lease_7p4q2r/revoke \
  -H "Authorization: Bearer mk_live_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Security incident: credential compromise suspected"
  }'

Response:

{
  "data": {
    "id": "lease_7p4q2r",
    "status": "revoked",
    "revoked_by": "user_jsmith",
    "revoked_reason": "Security incident: credential compromise suspected",
    "revoked_at": "2026-03-01T10:15:00Z"
  },
  "meta": {
    "request_id": "req_revoke001",
    "timestamp": "2026-03-01T10:15:00Z"
  }
}

Revoking All Leases for a Credential

In a security incident, revoke all active leases for a credential at once:

curl -X POST https://api.mitrity.com/api/v1/credentials/cred_8k2m4n/revoke-all \
  -H "Authorization: Bearer mk_live_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Credential rotation: replacing compromised key"
  }'

Response:

{
  "data": {
    "credential_id": "cred_8k2m4n",
    "leases_revoked": 3,
    "revoked_by": "user_jsmith",
    "revoked_reason": "Credential rotation: replacing compromised key",
    "revoked_at": "2026-03-01T10:15:00Z"
  },
  "meta": {
    "request_id": "req_revoke002",
    "timestamp": "2026-03-01T10:15:00Z"
  }
}

Cascading Revocation

When a grant is revoked, all active leases under that grant are automatically revoked. When a credential is deleted, all grants and leases are revoked.

Delete Credential
    │
    ├──► Revoke all Grants
    │       │
    │       └──► Revoke all Leases
    │
    └──► Log audit event

Credential Rotation

Manual Rotation

Update a credential's value. All active leases continue to use the old value until they expire. New leases receive the updated value:

curl -X PATCH https://api.mitrity.com/api/v1/credentials/cred_8k2m4n \
  -H "Authorization: Bearer mk_live_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "sk-proj-new-key-xyz789...",
    "revoke_active_leases": true
  }'

Setting revoke_active_leases: true forces all active leases to be revoked, ensuring all agents receive the new credential on their next lease request.

Rotation Reminders

Configure rotation reminders to alert when a credential has not been rotated within the specified interval:

{
  "metadata": {
    "rotation_interval_days": 90
  }
}

MITRITY sends a notification when the rotation interval is approaching (7 days before) and when it has elapsed.

Audit Trail

Every credential operation is logged in the audit log:

Event	Description	Logged Data
`credential.created`	New credential defined	Credential ID, name, type (value never logged)
`credential.updated`	Credential value or metadata updated	Credential ID, changed fields
`credential.deleted`	Credential removed	Credential ID, cascading revocations
`grant.created`	New grant assigned	Grant ID, credential ID, agent ID
`grant.revoked`	Grant revoked	Grant ID, reason, cascading revocations
`lease.created`	New lease issued	Lease ID, agent ID, TTL, justification
`lease.expired`	Lease TTL elapsed	Lease ID, duration
`lease.revoked`	Lease manually revoked	Lease ID, reason, who revoked
`lease.renewed`	Lease TTL extended	Lease ID, new TTL

Access the credential audit trail at Security > Credential Broker > Audit Log or via the standard audit API with the source=credential_broker filter.

Security Model

Encryption

Credential values are encrypted at rest using AES-256-GCM.
Each tenant has a unique encryption key derived from the tenant's root key.
Encryption keys are managed via GCP Secret Manager and never stored alongside the encrypted data.

Access Control

Only users with Owner or Manager roles can create credentials and grants.
Member and Viewer roles can view credential metadata but never the credential value.
The credential value is only accessible via an active lease, which requires a valid grant.

Isolation

Credentials are strictly tenant-isolated. No cross-tenant access is possible.
Environment-scoped credentials are only accessible to agents in that environment.

Best Practices

Use Short Lease TTLs

Default to the shortest lease TTL that supports your agent's workflow. A 15-minute TTL for an API call is better than a 24-hour TTL. Shorter leases reduce the window of exposure if a credential is compromised.

Require Justifications

Enable require_justification on grants for production credentials. This creates a paper trail of why each credential was accessed, which is invaluable during incident investigation.

Set Concurrent Lease Limits

Limit max_concurrent_leases to the minimum necessary. If an agent only makes sequential API calls, one concurrent lease is sufficient. Multiple concurrent leases may indicate credential sharing or misuse.

Rotate Credentials Regularly

Set rotation intervals and respond to rotation reminders promptly. A 90-day rotation interval is a reasonable default for API keys. Database passwords may warrant shorter intervals.

Monitor Lease Patterns

Unusual lease patterns — leases requested outside business hours, high renewal rates, or leases from unexpected agents — may indicate security issues. Review lease analytics in the dashboard.

Use Environment Scoping

Scope credentials to specific environments. A production database password should not be accessible to agents in the development environment.

Credential Broker

Overview

Credential Types

Defining Credentials

Via the Dashboard

Via the API

Credential Fields

Grants

Creating a Grant

Grant Fields

Listing Grants for a Credential

Revoking a Grant

Leases

Lease Lifecycle

Creating a Lease

Lease Fields

Renewing a Lease

Listing Active Leases

Revocation

Revoking a Single Lease

Revoking All Leases for a Credential

Cascading Revocation

Credential Rotation

Manual Rotation

Rotation Reminders

Audit Trail

Security Model

Encryption

Access Control

Isolation

Best Practices

Use Short Lease TTLs

Require Justifications

Set Concurrent Lease Limits

Rotate Credentials Regularly

Monitor Lease Patterns

Use Environment Scoping

Related Documentation