Authentication

The Operator API uses bearer authentication. Unless a page explicitly says otherwise, every request requires the Authorization header.

Authorization: Bearer {operator_api_key_or_staff_session}

Two bearer token families exist:

• operator API keys for server-to-server integration work
• staff session tokens for human dashboard sessions and staff-management APIs

Key model

• API key is operator-scoped.
• OpenPoly stores only the hash and metadata for the secret portion.
• Raw API keys are shown exactly once at creation time. Never log them; store the one-time value only in server-side secret storage.
• Browser clients must never receive an operator API key.

Request conventions

Parameter tables in this guide use these labels:

• Required: the request cannot be processed without the parameter.
• Conditionally required: required only for the stated mode or condition.
• Optional: may be omitted; the documented default or existing value is used.

For paginated list endpoints, page defaults to 1, page_size usually defaults to 50, and page_size is capped at 100. Pages with a different default state it explicitly. Invalid enum and date filters return 400 with an INVALID_* code. Invalid or non-positive pagination values fall back to the endpoint default.

Scope model

Requests are checked against the scope list attached to the active API key or staff session.

Common scopes:

• *
• launch:write
• users:read
• markets:read
• markets:write
• trades:read
• redemptions:read
• balance_operations:read
• wallet_adapter:read
• wallet_adapter:write
• api_keys:read
• api_keys:write
• webhooks:read
• webhooks:write
• simulator:read
• simulator:write
• staffs:read staff-session only
• staffs:write staff-session only

Failure behavior

• Missing or malformed bearer header -> 401 UNAUTHORIZED
• Invalid or revoked API key -> 401 INVALID_API_KEY
• Expired or revoked staff session -> 401 INVALID_OPERATOR_SESSION
• Missing required scope -> 403 INSUFFICIENT_SCOPE
• Staff-management API called with API key -> 403 STAFF_SESSION_REQUIRED

Errors use the standard H3/Nitro envelope:

{
  "statusCode": 401,
  "statusMessage": "INVALID_API_KEY",
  "message": "INVALID_API_KEY"
}

Security requirements

• Keep key in server-only secret storage.
• Rotate keys through dashboard or API key endpoints.
• Use least-privilege scopes for each integration service.
• Do not use API keys for browser clients or human staff-management workflows.