Scopes
Scopes
Scopes restrict the authenticated operator's own resources. Some routes require multiple grants; others additionally require a human staff session.
Supported scopes
launch:writeusers:readmarkets:readmarkets:writetrades:readredemptions:readsettlements:readbalance_operations:readpolyflight:readpolyflight_terms:readpolyflight_settlements:readwallet_adapter:readwallet_adapter:writeapi_keys:readapi_keys:writewebhooks:readwebhooks:writesimulator:readsimulator:writestaffs:readstaff-session onlystaffs:writestaff-session only*
* satisfies scope checks but never bypasses authentication type, operator ownership, product enablement, or staging-only restrictions.
API keys cannot be created with staffs:read or staffs:write. Staff-management, Operator Support, and Market Requests routes reject machine keys even with *. Staff memberships accept explicit assignable scopes, not a newly assigned *.
Endpoint mapping
| Scope | Endpoints |
|---|---|
launch:write | POST /api/operator/launch, POST /api/operator/users/portfolio-view |
users:read | GET /api/operator/users, GET /api/operator/users/portfolio, GET /api/operator/users/portfolio-view, POST /api/operator/users/portfolio-view |
markets:read | GET /api/operator/markets, GET /api/operator/markets/trending; staff-only Market Requests list/detail/options. |
markets:write | POST /api/operator/markets/{id}/visibility; staff-only POST /api/operator/market-requests. |
trades:read | GET /api/operator/trades, GET /api/operator/trades/{tradeId}, GET /api/operator/trades/{tradeId}/view, GET /api/operator/trades/{marketId}/{externalUserId} |
redemptions:read | GET /api/operator/resolutions, GET /api/operator/redemptions |
settlements:read | GET /api/operator/settlement-report, GET /api/operator/settlement-report/export for the authenticated operator's Opinion monthly report only. |
balance_operations:read | GET /api/operator/balance-operations |
polyflight:read | Polyflight overview; flights list/detail/export; tickets with companion terms scope; wallet operations with companion balance scope; Polyflight webhook evidence with companion webhook scope. |
polyflight_terms:read | Terms current/scheduled/history and, with polyflight:read, ticket list/detail/export because tickets expose frozen share BPS. |
polyflight_settlements:read | Finalized settlement-report list/detail/export, global/scoped payment history, and statement corrections. |
wallet_adapter:read | GET /api/operator/wallet-adapter |
wallet_adapter:write | PUT /api/operator/wallet-adapter, POST /api/operator/wallet-adapter/test |
api_keys:read | GET /api/operator/api-keys |
api_keys:write | POST /api/operator/api-keys, POST /api/operator/api-keys/{id}/revoke |
webhooks:read | GET /api/operator/webhooks/endpoints, GET /api/operator/webhooks/endpoints/history, GET /api/operator/webhooks/deliveries, GET /api/operator/webhooks/deliveries/export |
webhooks:write | POST /api/operator/webhooks/endpoints, PATCH /api/operator/webhooks/endpoints/{id}, DELETE /api/operator/webhooks/endpoints/{id}, POST /api/operator/webhooks/endpoints/{id}/delete, POST /api/operator/webhooks/deliveries/{id}/replay, POST /api/operator/webhooks/deliveries/resend. |
simulator:read | GET /api/operator/simulator/users, GET /api/operator/simulator/users/{id}, GET /api/operator/simulator/wallets/{externalUserId} |
simulator:write | POST /api/operator/simulator/users, PATCH /api/operator/simulator/users/{id}, POST /api/operator/simulator/users/{id}/operations, PUT /api/operator/simulator/wallets/{externalUserId}, POST /api/operator/simulator/operations |
staffs:read | GET /api/operator/staff with staff-session auth only |
staffs:write | POST /api/operator/staff, PATCH /api/operator/staff/{id}, POST /api/operator/staff/{id}/reset-password with staff-session auth only |
Polyflight ticket resources require both polyflight:read and polyflight_terms:read; balance-operation resources require both polyflight:read and balance_operations:read; webhook delivery evidence requires both polyflight:read and webhooks:read. Existing restricted viewer/API-key grants are not expanded automatically.
Compound reporting permissions
| Surface | Required grants |
|---|---|
Market PnL, GET /api/operator/market-pnl | Both trades:read and redemptions:read. |
Cash Flow Triage, GET /api/operator/market-pnl/issues and GET /api/operator/market-pnl/issues/{kind}/{sourceId} | All three: trades:read, redemptions:read, balance_operations:read. Operator access is read-only. |
| Historical callback recovery | API resend queueing requires webhooks:write; delivery inspection additionally needs webhooks:read. Selecting Polyflight/all delivery evidence also requires polyflight:read. There is no resend dry-run/preview API. |
| Dashboard Request Create Market | Staff session plus both markets:read and markets:write for options/form/submission. The POST API itself checks markets:write. |
Portfolio HTML launch, POST /api/operator/users/portfolio-view | Both users:read and launch:write; a reporting-only key cannot mint launches through HTML controls. |
| UAT saved-adapter checks | wallet_adapter:read to load saved configuration and wallet_adapter:write to call the check. Subscription readiness additionally needs webhooks:read; product evidence retains its own companion scopes. |
Human-only workflows
Operator Support needs an active staff session, with no additional trading/wallet/settlement scope. Its list, create, detail, message, and reopen routes are all operator-scoped; there is no operator close endpoint.
Market Requests also require staff sessions, in addition to the route's market scope. Availability depends on rollout and operator onboarding. An API key is not an alternative to human risk acceptance.
Recommended key split
- server-side launch key:
launch:write - reporting key: read scopes only
- resolved-market cash reporting key:
trades:readandredemptions:read; addbalance_operations:readonly for triage evidence - Opinion monthly reporting key:
settlements:read; no trade, redemption, or Polyflight scopes are required for this report and its exports - webhook admin key:
webhooks:read,webhooks:write - wallet adapter admin key:
wallet_adapter:read,wallet_adapter:write - simulator key for staging only:
simulator:read,simulator:write - Polyflight reporting key:
polyflight:read, addingpolyflight_terms:read,polyflight_settlements:read,balance_operations:read, orwebhooks:readonly for needed resources - staff access stays in staff sessions, not API keys
Polyflight scopes are assignable; they are not added automatically to existing restricted grants. Operator scopes are read-only for commercial terms, statement finalization/payments, and wallet manual resolution.
Opinion settlements:read is a new separate grant from redemptions:read and polyflight_settlements:read. Existing wildcard administrators retain access; non-wildcard users, viewer defaults, and restricted API keys do not gain access automatically. Explicitly assign it when needed. It authorizes read-only own-operator reports/exports, not bank payments or accounting mutations.
Dashboard navigation uses effective scopes, including all-of requirements above. Session refresh retrieves current permissions; ordinary staff-access edits invalidate sessions. If a page is unavailable, confirm the staff grant and sign in again when necessary instead of substituting a broad machine key.
Rotation rule
Do not reuse one broad key everywhere. Split by workload and rotate independently.