API Keys

Manage API keys for programmatic access to Mandatum.

Endpoints

Create API Key

POST /v1/api-keys

Create a new API key.

Request:

{
  "name": "Production Backend",
  "type": "live",
  "expires_at": "2026-01-15T00:00:00Z",
  "permissions": ["prompts:read", "prompts:write", "requests:read"]
}

Response:

{
  "data": {
    "id": "key_abc123",
    "name": "Production Backend",
    "key": "mdt_live_abc123def456...",
    "type": "live",
    "permissions": ["prompts:read", "prompts:write", "requests:read"],
    "expires_at": "2026-01-15T00:00:00Z",
    "created_at": "2025-01-15T10:00:00Z"
  }
}

WARNING

The API key is only shown once during creation. Store it securely.

List API Keys

GET /v1/api-keys

List all API keys for your account.

Response:

{
  "data": [
    {
      "id": "key_abc123",
      "name": "Production Backend",
      "type": "live",
      "key_prefix": "mdt_live_abc",
      "permissions": ["prompts:read", "prompts:write"],
      "expires_at": "2026-01-15T00:00:00Z",
      "last_used_at": "2025-01-15T09:30:00Z",
      "created_at": "2025-01-15T10:00:00Z"
    }
  ]
}

Get API Key

GET /v1/api-keys/{key_id}

Get details for a specific API key.

Response:

{
  "data": {
    "id": "key_abc123",
    "name": "Production Backend",
    "type": "live",
    "key_prefix": "mdt_live_abc",
    "permissions": ["prompts:read", "prompts:write"],
    "usage": {
      "requests_last_30d": 15234,
      "requests_today": 567
    },
    "expires_at": "2026-01-15T00:00:00Z",
    "last_used_at": "2025-01-15T09:30:00Z",
    "created_at": "2025-01-15T10:00:00Z"
  }
}

Update API Key

PATCH /v1/api-keys/{key_id}

Update API key properties.

Request:

{
  "name": "Production Backend (Updated)",
  "permissions": ["prompts:read", "prompts:write", "requests:read", "requests:write"]
}

Response:

{
  "data": {
    "id": "key_abc123",
    "name": "Production Backend (Updated)",
    "permissions": ["prompts:read", "prompts:write", "requests:read", "requests:write"],
    "updated_at": "2025-01-15T11:00:00Z"
  }
}

Delete API Key

DELETE /v1/api-keys/{key_id}

Revoke an API key.

Response:

{
  "data": {
    "deleted": true,
    "id": "key_abc123",
    "deleted_at": "2025-01-15T10:00:00Z"
  }
}

Key Types

Live Keys

Production keys with full access:

{
  "type": "live",
  "prefix": "mdt_live_"
}

Use for:

• Production applications
• Real LLM calls
• Actual billing

Test Keys

Development keys with sandbox access:

{
  "type": "test",
  "prefix": "mdt_test_"
}

Use for:

• Development and testing
• No actual LLM costs
• Rate limited to 60 req/min

Permissions

Granular permissions for API keys:

Permission	Description
prompts:read	List and view prompts
prompts:write	Create, update, delete prompts
prompts:run	Execute prompts
integrations:read	View integration code
integrations:write	Create, update integration code
requests:read	View request logs
requests:write	Import historical requests
requests:delete	Delete requests (GDPR)
analytics:read	View analytics
webhooks:read	View webhooks
webhooks:write	Create, update webhooks
api_keys:read	View API keys
api_keys:write	Create, update API keys

Permission Sets

Common permission combinations:

Read-only:

{
  "permissions": [
    "prompts:read",
    "requests:read",
    "analytics:read"
  ]
}

Developer:

{
  "permissions": [
    "prompts:read",
    "prompts:write",
    "prompts:run",
    "integrations:read",
    "integrations:write",
    "requests:read"
  ]
}

Admin:

{
  "permissions": ["*"]
}

Examples

Python SDK

from mandatum import Mandatum

client = Mandatum(api_key="your-api-key")

# Create API key
key = client.api_keys.create(
    name="Production Backend",
    type="live",
    permissions=["prompts:read", "prompts:write", "prompts:run"],
    expires_at="2026-01-15T00:00:00Z"
)

print(f"API Key: {key.key}")
print(f"Store this securely - it won't be shown again")

# List API keys
keys = client.api_keys.list()

for key in keys:
    print(f"{key.name}: {key.key_prefix}... (last used: {key.last_used_at})")

# Get key details
key = client.api_keys.get("key_abc123")
print(f"Requests (30d): {key.usage.requests_last_30d}")

# Update permissions
client.api_keys.update(
    key_id="key_abc123",
    permissions=["prompts:read", "prompts:run"]
)

# Revoke key
client.api_keys.delete("key_abc123")

TypeScript SDK

Coming Soon

A TypeScript/JavaScript SDK is in development. For now, use the REST API directly.

cURL

# Create API key
curl -X POST https://mandatum-api.gavelinivar.com/api/v1/api-keys \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Backend",
    "type": "live",
    "permissions": ["prompts:read", "prompts:write"],
    "expires_at": "2026-01-15T00:00:00Z"
  }'

# List API keys
curl -X GET https://mandatum-api.gavelinivar.com/api/v1/api-keys \
  -H "Authorization: Bearer YOUR_API_KEY"

# Revoke API key
curl -X DELETE https://mandatum-api.gavelinivar.com/api/v1/api-keys/key_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Security Best Practices

Rotation

Rotate keys regularly:

# Create new key
new_key = client.api_keys.create(
    name="Production Backend (2025-Q1)",
    type="live",
    permissions=["prompts:read", "prompts:write"]
)

# Update application with new key
update_application_config(new_key.key)

# Verify new key works
test_with_new_key(new_key.key)

# Revoke old key
client.api_keys.delete(old_key_id)

Monitoring

Monitor API key usage:

# Get key usage
key = client.api_keys.get("key_abc123")

if key.usage.requests_today > 10000:
    alert("High API key usage detected")

if key.last_used_at < datetime.now() - timedelta(days=30):
    alert("API key not used in 30 days - consider revoking")

Environment Separation

Use different keys per environment:

# Development
export MANDATUM_API_KEY="mdt_test_dev123..."

# Staging
export MANDATUM_API_KEY="mdt_test_staging123..."

# Production
export MANDATUM_API_KEY="mdt_live_prod123..."

Rate Limits

Rate limits apply per API key:

Key Type	Requests/Minute	Requests/Day
Test	60	1,000
Live (Free)	60	1,000
Live (Pro)	600	100,000
Live (Enterprise)	Custom	Custom

See Also

• Authentication Guide
• API Overview