Admin API

This endpoint requires admin-level roles (platform_admin, tenant_admin, or system_admin). Accessible via the API gateway at /v1/platform/*.

Planned Feature

The API key system is not yet implemented. This documentation describes the planned design. Currently, all API access uses JWT authentication exclusively.

API Keys API

Manage API keys, configure scopes, set rate limits, and monitor usage.

Overview

Attribute	Value
Base Path	`/api/v1/api-keys`
Authentication	Bearer Token (Admin)
Required Roles	`platform_admin`, `system_admin`, `super_admin`

API Keys

List API Keys

GET /api/v1/api-keys

Query Parameters

Parameter	Type	Description
`status`	string	`active`, `revoked`, `expired`
`type`	string	`live`, `test`
`created_by`	uuid	Filter by creator

Response

{
  "api_keys": [
    {
      "id": "key_001",
      "name": "Production Integration",
      "key_prefix": "olym_live_abc",
      "type": "live",
      "status": "active",
      "scopes": ["orders:read", "orders:write", "payments:read"],
      "created_by": {
        "id": "user_001",
        "email": "admin@example.com"
      },
      "last_used": "2026-01-24T19:30:00Z",
      "usage": {
        "requests_24h": 15420,
        "requests_30d": 450000
      },
      "created_at": "2025-06-01T00:00:00Z",
      "expires_at": null
    },
    {
      "id": "key_002",
      "name": "Test Environment",
      "key_prefix": "olym_test_xyz",
      "type": "test",
      "status": "active",
      "scopes": ["*"],
      "created_by": {
        "id": "user_001",
        "email": "admin@example.com"
      },
      "last_used": "2026-01-24T18:00:00Z",
      "usage": {
        "requests_24h": 250,
        "requests_30d": 5000
      },
      "created_at": "2025-06-01T00:00:00Z",
      "expires_at": null
    }
  ],
  "total": 5
}

Create API Key

POST /api/v1/api-keys

Request Body

{
  "name": "Mobile App Integration",
  "type": "live",
  "scopes": [
    "orders:read",
    "orders:write",
    "menu:read",
    "customers:read",
    "customers:write"
  ],
  "restrictions": {
    "ip_allowlist": ["203.0.113.0/24"],
    "locations": ["loc_123", "loc_456"],
    "rate_limit": {
      "requests_per_minute": 100,
      "requests_per_day": 50000
    }
  },
  "expires_at": "2027-01-01T00:00:00Z",
  "metadata": {
    "app": "mobile_ios",
    "version": "2.0"
  }
}

Response

{
  "id": "key_003",
  "name": "Mobile App Integration",
  "key": "olym_live_EXAMPLE_KEY_1234567890abcdef",
  "key_prefix": "olym_live_abc",
  "type": "live",
  "status": "active",
  "scopes": [
    "orders:read",
    "orders:write",
    "menu:read",
    "customers:read",
    "customers:write"
  ],
  "restrictions": {
    "ip_allowlist": ["203.0.113.0/24"],
    "locations": ["loc_123", "loc_456"],
    "rate_limit": {
      "requests_per_minute": 100,
      "requests_per_day": 50000
    }
  },
  "expires_at": "2027-01-01T00:00:00Z",
  "created_at": "2026-01-24T19:30:00Z",
  "warning": "This is the only time the full key will be shown. Store it securely."
}

Get API Key

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

Response

{
  "id": "key_001",
  "name": "Production Integration",
  "key_prefix": "olym_live_abc",
  "type": "live",
  "status": "active",
  "scopes": ["orders:read", "orders:write", "payments:read"],
  "restrictions": {
    "ip_allowlist": [],
    "locations": null,
    "rate_limit": {
      "requests_per_minute": 1000,
      "requests_per_day": 100000
    }
  },
  "created_by": {
    "id": "user_001",
    "email": "admin@example.com",
    "name": "John Admin"
  },
  "usage": {
    "total_requests": 2500000,
    "requests_24h": 15420,
    "requests_7d": 105000,
    "requests_30d": 450000,
    "last_used": "2026-01-24T19:30:00Z",
    "last_ip": "203.0.113.50"
  },
  "errors": {
    "count_24h": 25,
    "rate_limited_24h": 0,
    "auth_failures_24h": 2
  },
  "metadata": {
    "integration": "main_pos"
  },
  "created_at": "2025-06-01T00:00:00Z",
  "updated_at": "2026-01-20T00:00:00Z",
  "expires_at": null
}

Update API Key

PUT /api/v1/api-keys/{key_id}

Request Body

{
  "name": "Production Integration (Updated)",
  "scopes": [
    "orders:read",
    "orders:write",
    "payments:read",
    "payments:write"
  ],
  "restrictions": {
    "rate_limit": {
      "requests_per_minute": 2000
    }
  }
}

Revoke API Key

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

Request Body

{
  "reason": "Key compromised",
  "immediate": true
}

Response

{
  "id": "key_001",
  "status": "revoked",
  "revoked_at": "2026-01-24T19:30:00Z",
  "revoked_by": {
    "id": "user_001",
    "email": "admin@example.com"
  },
  "reason": "Key compromised"
}

Regenerate API Key

POST /api/v1/api-keys/{key_id}/regenerate

Request Body

{
  "keep_old_active_hours": 24
}

Response

{
  "id": "key_001",
  "new_key": "olym_live_NEWKEY_EXAMPLE_12345",
  "old_key_expires_at": "2026-01-25T19:30:00Z",
  "regenerated_at": "2026-01-24T19:30:00Z"
}

Scopes

List Available Scopes

GET /api/v1/api-keys/scopes

Response

{
  "scopes": [
    {
      "name": "orders:read",
      "description": "Read order information",
      "category": "orders"
    },
    {
      "name": "orders:write",
      "description": "Create and update orders",
      "category": "orders"
    },
    {
      "name": "payments:read",
      "description": "View payment information",
      "category": "payments"
    },
    {
      "name": "payments:write",
      "description": "Process payments and refunds",
      "category": "payments",
      "sensitive": true
    },
    {
      "name": "customers:read",
      "description": "View customer information",
      "category": "customers"
    },
    {
      "name": "customers:write",
      "description": "Create and update customers",
      "category": "customers"
    },
    {
      "name": "menu:read",
      "description": "View menu items and categories",
      "category": "menu"
    },
    {
      "name": "menu:write",
      "description": "Modify menu items",
      "category": "menu"
    },
    {
      "name": "inventory:read",
      "description": "View inventory levels",
      "category": "inventory"
    },
    {
      "name": "inventory:write",
      "description": "Update inventory",
      "category": "inventory"
    },
    {
      "name": "employees:read",
      "description": "View employee information",
      "category": "employees",
      "sensitive": true
    },
    {
      "name": "reports:read",
      "description": "Access reports and analytics",
      "category": "reports"
    },
    {
      "name": "webhooks:write",
      "description": "Manage webhooks",
      "category": "platform"
    },
    {
      "name": "*",
      "description": "Full access (all scopes)",
      "category": "admin",
      "sensitive": true
    }
  ],
  "categories": [
    "orders",
    "payments",
    "customers",
    "menu",
    "inventory",
    "employees",
    "reports",
    "platform",
    "admin"
  ]
}

Usage & Analytics

Get Key Usage

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

Query Parameters

Parameter	Type	Description
`period`	string	`hour`, `day`, `week`, `month`
`start_date`	date	Custom period start
`end_date`	date	Custom period end

Response

{
  "key_id": "key_001",
  "period": "day",
  "summary": {
    "total_requests": 15420,
    "successful_requests": 15395,
    "failed_requests": 25,
    "success_rate": 0.9984,
    "avg_latency_ms": 125,
    "p95_latency_ms": 280,
    "p99_latency_ms": 450
  },
  "by_endpoint": [
    {
      "endpoint": "GET /api/v1/orders",
      "requests": 5200,
      "avg_latency_ms": 95
    },
    {
      "endpoint": "POST /api/v1/orders",
      "requests": 3100,
      "avg_latency_ms": 180
    },
    {
      "endpoint": "GET /api/v1/menu",
      "requests": 4500,
      "avg_latency_ms": 45
    }
  ],
  "by_hour": [
    {"hour": "00:00", "requests": 250},
    {"hour": "01:00", "requests": 180},
    {"hour": "11:00", "requests": 1850},
    {"hour": "12:00", "requests": 2100}
  ],
  "by_status_code": {
    "200": 12500,
    "201": 2800,
    "400": 15,
    "401": 2,
    "429": 0,
    "500": 8
  },
  "errors": [
    {
      "code": "invalid_request",
      "count": 15,
      "last_seen": "2026-01-24T18:45:00Z"
    },
    {
      "code": "server_error",
      "count": 8,
      "last_seen": "2026-01-24T12:30:00Z"
    }
  ]
}

Get Rate Limit Status

GET /api/v1/api-keys/{key_id}/rate-limit

Response

{
  "key_id": "key_001",
  "limits": {
    "requests_per_minute": {
      "limit": 1000,
      "current": 45,
      "remaining": 955,
      "resets_at": "2026-01-24T19:31:00Z"
    },
    "requests_per_day": {
      "limit": 100000,
      "current": 15420,
      "remaining": 84580,
      "resets_at": "2026-01-25T00:00:00Z"
    }
  },
  "currently_limited": false,
  "rate_limit_history": {
    "limited_count_24h": 0,
    "limited_count_7d": 2
  }
}

Audit Log

Get Key Activity Log

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

Query Parameters

Parameter	Type	Description
`action`	string	`created`, `updated`, `revoked`, `used`
`start_date`	datetime	Period start

Response

{
  "events": [
    {
      "timestamp": "2026-01-24T19:30:00Z",
      "action": "key_used",
      "ip_address": "203.0.113.50",
      "endpoint": "POST /api/v1/orders",
      "user_agent": "OlympusSDK/2.0"
    },
    {
      "timestamp": "2026-01-20T10:00:00Z",
      "action": "scopes_updated",
      "actor": {
        "id": "user_001",
        "email": "admin@example.com"
      },
      "changes": {
        "scopes_added": ["payments:write"],
        "scopes_removed": []
      }
    },
    {
      "timestamp": "2025-06-01T00:00:00Z",
      "action": "key_created",
      "actor": {
        "id": "user_001",
        "email": "admin@example.com"
      }
    }
  ]
}

Key Policies

Get Key Policies

GET /api/v1/api-keys/policies

Response

{
  "policies": {
    "max_keys_per_tenant": 50,
    "key_expiration": {
      "live_keys": {
        "max_lifetime_days": null,
        "require_expiration": false
      },
      "test_keys": {
        "max_lifetime_days": 365,
        "require_expiration": false
      }
    },
    "scope_restrictions": {
      "sensitive_scopes_require_approval": true,
      "sensitive_scopes": ["payments:write", "employees:read", "*"]
    },
    "rotation_policy": {
      "recommended_rotation_days": 90,
      "force_rotation_days": null
    }
  }
}

Webhooks

Event	Description
`api_key.created`	New API key created
`api_key.updated`	API key settings updated
`api_key.revoked`	API key revoked
`api_key.rate_limited`	Key hit rate limit
`api_key.expiring`	Key expiring soon

Error Responses

Status	Code	Description
400	`invalid_scopes`	One or more scopes invalid
403	`scope_not_allowed`	Scope requires approval
404	`key_not_found`	API key not found
409	`key_already_revoked`	Key already revoked
429	`rate_limited`	Rate limit exceeded

Authentication - Authentication guide
API Gateway - Gateway auth
Rate Limiting - Rate limit details

Overview​

API Keys​

List API Keys​

Create API Key​

Get API Key​

Update API Key​

Revoke API Key​

Regenerate API Key​

Scopes​

List Available Scopes​

Usage & Analytics​

Get Key Usage​

Get Rate Limit Status​

Audit Log​

Get Key Activity Log​

Key Policies​

Get Key Policies​

Webhooks​

Error Responses​

Related Documentation​

Overview

API Keys

List API Keys

Create API Key

Get API Key

Update API Key

Revoke API Key

Regenerate API Key

Scopes

List Available Scopes

Usage & Analytics

Get Key Usage

Get Rate Limit Status

Audit Log

Get Key Activity Log

Key Policies

Get Key Policies

Webhooks

Error Responses

Related Documentation