API Keys Rail

API Keys Rail

API key management, rotation, and access control.

Overview

The API Keys Rail provides endpoints for creating, managing, and securing API keys for programmatic access.

Base URL

/api/v1/api-keys

Endpoints

Create API Key

POST /api/v1/api-keys

Create a new API key.

Request Body:

{
  "name": "Production Integration",
  "type": "SECRET",
  "scopes": ["contracts:read", "contracts:write", "kyc:read"],
  "expiresAt": "2026-01-15",
  "ipWhitelist": ["192.168.1.0/24", "10.0.0.0/8"],
  "rateLimit": 1000,
  "metadata": {
    "environment": "production",
    "team": "backend"
  }
}

Response:

{
  "data": {
    "keyId": "key_abc123",
    "name": "Production Integration",
    "key": "IOF_GENERATED_KEY_SHOWN_ONCE",
    "prefix": "sk_live",
    "type": "SECRET",
    "scopes": ["contracts:read", "contracts:write", "kyc:read"],
    "expiresAt": "2026-01-15T00:00:00Z",
    "createdAt": "2025-01-15T10:00:00Z"
  }
}

::: caution The full API key is only shown once. Store it securely. :::

List API Keys

GET /api/v1/api-keys

List all API keys.

Query Parameters:

Parameter	Type	Description
type	string	Filter by key type
status	string	Filter by status

Response:

{
  "data": [
    {
      "keyId": "key_abc123",
      "name": "Production Integration",
      "prefix": "sk_live_xxx",
      "type": "SECRET",
      "status": "ACTIVE",
      "lastUsedAt": "2025-01-15T09:30:00Z",
      "expiresAt": "2026-01-15T00:00:00Z"
    }
  ]
}

Get API Key

GET /api/v1/api-keys/:keyId

Get API key details (not the key itself).

Update API Key

PATCH /api/v1/api-keys/:keyId

Update API key settings.

Request Body:

{
  "name": "Production Integration (Updated)",
  "scopes": ["contracts:read"],
  "ipWhitelist": ["192.168.1.0/24"]
}

Rotate API Key

POST /api/v1/api-keys/:keyId/rotate

Rotate an API key.

Request Body:

{
  "gracePeriod": "24h"
}

Response:

{
  "data": {
    "keyId": "key_abc123",
    "newKey": "IOF_ROTATED_KEY_SHOWN_ONCE",
    "oldKeyValidUntil": "2025-01-16T10:00:00Z"
  }
}

Revoke API Key

DELETE /api/v1/api-keys/:keyId

Revoke an API key.

Get Key Usage

GET /api/v1/api-keys/:keyId/usage

Get API key usage statistics.

Query Parameters:

Parameter	Type	Description
period	string	HOURLY, DAILY, MONTHLY
from	string	Start date
to	string	End date

Response:

{
  "data": {
    "keyId": "key_abc123",
    "period": "DAILY",
    "usage": [
      {
        "date": "2025-01-15",
        "requests": 15420,
        "errors": 23,
        "latencyP50": 45,
        "latencyP99": 250
      }
    ],
    "totals": {
      "requests": 150000,
      "errors": 230
    }
  }
}

Validate Key

POST /api/v1/api-keys/validate

Validate an API key.

Request Body:

{
  "key": "${IOF_API_KEY}"
}

Response:

{
  "data": {
    "valid": true,
    "keyId": "key_abc123",
    "scopes": ["contracts:read", "contracts:write"],
    "tenantId": "tenant_123"
  }
}

Key Types

Type	Prefix	Description
SECRET	sk_	Full access (server-side)
PUBLISHABLE	pk_	Limited access (client-side)
RESTRICTED	rk_	Restricted scope

Key Status

Status	Description
ACTIVE	Key is active
ROTATING	Key is being rotated
EXPIRED	Key has expired
REVOKED	Key was revoked

Scopes

Scope	Description
contracts:read	Read contracts
contracts:write	Create/update contracts
kyc:read	Read KYC data
kyc:write	Submit KYC
admin	Full admin access

Events

Event	Description
api_key.created	Key created
api_key.rotated	Key rotated
api_key.revoked	Key revoked
api_key.expired	Key expired
api_key.used	Key used (audit)

See Also

• Auth Rail - Authentication
• OAuth2 Rail - OAuth 2.0