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, staff management, private market requests, and operator support

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 most paginated list endpoints, page defaults to 1 (maximum 10000), page_size defaults to 50 (maximum 100), and non-positive/unparseable pagination values fall back to defaults. Invalid enum/date filters return 400 INVALID_*. Endpoint-specific rules take precedence: Market PnL and Resolutions default to 25 rows; private market requests and support use strict camelCase pageSize with a default of 20 and reject invalid values. Portfolio controls also document their own validation.

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
• settlements:read Opinion monthly reports and exports
• 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

Polyflight also has polyflight:read, polyflight_terms:read, and polyflight_settlements:read; enabling a product and granting its scopes are separate requirements.

Auth-type restrictions

Wildcard scope does not bypass staff-only or operator-ownership restrictions. There is no operator cash-confirmation/write scope. Staff scopes are read from the current active membership on each request; they are not a frozen grant embedded in the bearer token.

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.