API Keys Service

API key validation and management service with rate limiting, tenant isolation, and atomic usage tracking. Provides endpoints for key validation and admin key management.

Service Architecture

REST Endpoints

Health

Public Endpoints

Admin Endpoints

Validate API Key

GET /api/keys/validate
X-API-Key: tz_live_abc123...

Response

{
  "valid": true,
  "tenantId": "tenant_abc123",
  "scopes": ["read", "write"],
  "rateLimit": {
    "limit": 1000,
    "remaining": 995,
    "resetsAt": "2024-01-15T11:00:00Z"
  }
}

Create API Key (Admin)

POST /api/keys
X-Admin-API-Key: admin-secret-key
Content-Type: application/json

{
  "tenantId": "tenant_abc123",
  "name": "Production API Key",
  "scopes": ["read", "write"],
  "rateLimit": 1000,
  "expiresAt": "2025-01-15T00:00:00Z"
}

Response

{
  "data": {
    "id": "key_xyz789",
    "tenantId": "tenant_abc123",
    "name": "Production API Key",
    "key": "tz_live_xyz789...",
    "scopes": ["read", "write"],
    "rateLimit": 1000,
    "expiresAt": "2025-01-15T00:00:00Z",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Important: The full API key is only returned once at creation. Store it securely.

List Tenant Keys (Admin)

GET /api/keys/tenant/tenant_abc123
X-Admin-API-Key: admin-secret-key

Response

{
  "data": [
    {
      "id": "key_xyz789",
      "name": "Production API Key",
      "prefix": "tz_live_xyz",
      "scopes": ["read", "write"],
      "rateLimit": 1000,
      "lastUsed": "2024-01-15T10:30:00Z",
      "expiresAt": "2025-01-15T00:00:00Z",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ]
}

Revoke API Key (Admin)

DELETE /api/keys/key_xyz789
X-Admin-API-Key: admin-secret-key

Response

{
  "success": true,
  "message": "API key revoked"
}

Authentication

API Key Validation

Include the API key in requests:

X-API-Key: tz_live_abc123...

Admin Authentication

Admin endpoints require the admin API key:

X-Admin-API-Key: your-admin-secret

API Key Format

Scopes

Rate Limiting

Each API key has a configurable rate limit. The service uses atomic counters to ensure accurate tracking without race conditions.

• Default limit: 1000 requests per minute
• Rate limit headers included in all responses
• 429 status returned when limit exceeded

Security

• API keys stored as SHA-256 hashes only
• IP allowlist enforcement for admin endpoints
• Constant-time comparison for key validation
• Multi-tenant isolation via tenant_id

Error Codes