API Keys

Create and manage API keys for authentication.

API Key Prefixes

Prefix	Type	Description
gw_dev_	Development	For testing, limited rate limits
gw_prod_	Production	For production use
gw_admin_	Admin	Full management access
gw_tenant_	Tenant	Multi-tenant customer keys

List API Keys

Endpoint

GET /v1/management/api-keys

Example

curl https://api.gateflow.ai/v1/management/api-keys \
  -H "Authorization: Bearer gw_admin_..."

Response

{
  "object": "list",
  "data": [
    {
      "id": "key_abc123",
      "name": "production-key",
      "prefix": "gw_prod_",
      "created_at": "2026-02-01T10:00:00Z",
      "last_used_at": "2026-02-16T09:45:00Z",
      "status": "active",
      "rate_limits": {
        "rpm": 1000,
        "tpm": 100000
      },
      "permissions": ["chat", "embeddings", "audio"]
    },
    {
      "id": "key_def456",
      "name": "development-key",
      "prefix": "gw_dev_",
      "created_at": "2026-01-15T10:00:00Z",
      "last_used_at": "2026-02-15T14:30:00Z",
      "status": "active",
      "rate_limits": {
        "rpm": 100,
        "tpm": 10000
      },
      "permissions": ["chat", "embeddings"]
    }
  ]
}

Create API Key

Endpoint

POST /v1/management/api-keys

Request Body

Parameter	Type	Required	Description
name	string	Yes	Descriptive name
type	string	No	dev, prod, or admin (default: prod)
permissions	array	No	Allowed operations
rate_limits	object	No	Custom rate limits
expires_at	string	No	Expiration timestamp
allowed_models	array	No	Restrict to specific models
allowed_ips	array	No	IP allowlist

Example

curl -X POST https://api.gateflow.ai/v1/management/api-keys \
  -H "Authorization: Bearer gw_admin_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "backend-service",
    "type": "prod",
    "permissions": ["chat", "embeddings"],
    "rate_limits": {
      "rpm": 500,
      "tpm": 50000,
      "daily_requests": 10000
    },
    "allowed_models": ["gpt-5.2", "gpt-5-mini", "text-embedding-3-large"]
  }'

Response

{
  "id": "key_xyz789",
  "name": "backend-service",
  "key": "gw_prod_abc123xyz789...",
  "prefix": "gw_prod_",
  "created_at": "2026-02-16T10:00:00Z",
  "status": "active",
  "rate_limits": {
    "rpm": 500,
    "tpm": 50000,
    "daily_requests": 10000
  },
  "permissions": ["chat", "embeddings"],
  "allowed_models": ["gpt-5.2", "gpt-5-mini", "text-embedding-3-large"]
}

WARNING

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

Get API Key

Endpoint

GET /v1/management/api-keys/{key_id}

Example

curl https://api.gateflow.ai/v1/management/api-keys/key_abc123 \
  -H "Authorization: Bearer gw_admin_..."

Response

{
  "id": "key_abc123",
  "name": "production-key",
  "prefix": "gw_prod_",
  "created_at": "2026-02-01T10:00:00Z",
  "last_used_at": "2026-02-16T09:45:00Z",
  "status": "active",
  "rate_limits": {
    "rpm": 1000,
    "tpm": 100000
  },
  "permissions": ["chat", "embeddings", "audio"],
  "usage": {
    "requests_today": 2500,
    "tokens_today": 450000,
    "cost_today_usd": 4.50
  }
}

Update API Key

Endpoint

PATCH /v1/management/api-keys/{key_id}

Example

curl -X PATCH https://api.gateflow.ai/v1/management/api-keys/key_abc123 \
  -H "Authorization: Bearer gw_admin_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-key-v2",
    "rate_limits": {
      "rpm": 2000,
      "tpm": 200000
    }
  }'

Response

{
  "id": "key_abc123",
  "name": "production-key-v2",
  "rate_limits": {
    "rpm": 2000,
    "tpm": 200000
  },
  "updated_at": "2026-02-16T10:30:00Z"
}

Rotate API Key

Generate a new key while keeping the same settings.

Endpoint

POST /v1/management/api-keys/{key_id}/rotate

Request Body

Parameter	Type	Description
grace_period_hours	integer	Hours to keep old key valid (default: 24)

Example

curl -X POST https://api.gateflow.ai/v1/management/api-keys/key_abc123/rotate \
  -H "Authorization: Bearer gw_admin_..." \
  -H "Content-Type: application/json" \
  -d '{
    "grace_period_hours": 48
  }'

Response

{
  "id": "key_abc123",
  "new_key": "gw_prod_newkey123...",
  "old_key_expires_at": "2026-02-18T10:00:00Z",
  "rotated_at": "2026-02-16T10:00:00Z"
}

Revoke API Key

Endpoint

POST /v1/management/api-keys/{key_id}/revoke

Example

curl -X POST https://api.gateflow.ai/v1/management/api-keys/key_abc123/revoke \
  -H "Authorization: Bearer gw_admin_..."

Response

{
  "id": "key_abc123",
  "status": "revoked",
  "revoked_at": "2026-02-16T10:00:00Z"
}

Delete API Key

Permanently delete an API key.

Endpoint

DELETE /v1/management/api-keys/{key_id}

Example

curl -X DELETE https://api.gateflow.ai/v1/management/api-keys/key_abc123 \
  -H "Authorization: Bearer gw_admin_..."

Response

{
  "id": "key_abc123",
  "deleted": true
}

API Key Permissions

Permission	Description
chat	Chat completions API
embeddings	Embeddings API
audio	Audio transcription and speech
files	File upload and management
models	List models
management	Management API access
admin	Full admin access

Setting Permissions

curl -X POST https://api.gateflow.ai/v1/management/api-keys \
  -H "Authorization: Bearer gw_admin_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "chat-only-key",
    "permissions": ["chat", "models"]
  }'

Errors

Code	Description
400	Invalid parameters
401	Invalid admin key
403	Insufficient permissions
404	API key not found
429	Rate limit exceeded

See Also

• Key Rotation - Rotation guide
• Organizations & RBAC - Access control
• API Key Management - Best practices