API keys

Open Operator Dashboard → Integrations → API Keys (/settings/api-keys). Reading keys requires api_keys:read; creating and revoking requires api_keys:write. These credentials authenticate machine-to-machine API requests. Dashboard sign-in requires a human staff account, not an API key.

Recommended key split

• launch key: launch:write
• reporting key: read scopes only, such as users:read, markets:read, trades:read, redemptions:read, and balance_operations:read; add settlements:read only when Opinion monthly settlement reports and exports are needed
• market visibility automation key: markets:read, markets:write
• wallet adapter automation key: wallet_adapter:read, wallet_adapter:write only when a backend service must manage adapter config
• webhook admin key: webhooks:read, webhooks:write
• staging simulator key: simulator:read, simulator:write
• Polyflight reporting key: grant only the needed polyflight:read, polyflight_terms:read, polyflight_settlements:read, and balance_operations:read; ticket reads require both polyflight:read and polyflight_terms:read.

Avoid one all-purpose key unless operationally necessary.

Staff management, Operator Support conversations, and private Market Requests require a human staff session; even wildcard API keys cannot access these staff-only workflows.

Create flow

1. Select Create API Key and name the workload and environment clearly.
2. Explicitly review the selected scopes. The form can initially select * for wildcard staff or all assignable scopes for restricted staff; this is not a least-privilege recommendation.
3. Keep only the minimum needed scopes. Restricted staff can assign only scopes they already hold; only wildcard staff can issue *.
4. Create the key and copy the full token from Copy token now into your backend secret manager. It is returned only at creation; the list retains a prefix, scopes, last-used timestamp, and revocation status, not a recoverable token.
5. Use the key only from trusted backend systems in the matching environment, never Mini App/browser code.

See scope list at /docs/reference/scopes.

Rotation flow

1. create replacement key first
2. deploy replacement secret to operator systems
3. verify new key works
4. revoke old key

Do not revoke old key before replacement is live.

Rotation is replacement plus revocation; this page does not edit an existing key's scopes or recover its token. Revocation is not an undoable pause. If the token is lost, create a replacement and revoke the lost key.

Revocation guidance

Revoke immediately if:

• token leaked to logs or chat
• token committed to repo
• token shared outside approved operators
• unknown traffic appears

Troubleshooting

• INVALID_API_KEY -> token wrong, revoked, or sent to wrong environment
• INSUFFICIENT_SCOPE -> wrong scope set
• INVALID_SCOPES during creation -> unsupported scope name
• staffs:read and staffs:write are not valid API key scopes
• CANNOT_ASSIGN_SCOPE -> a requested scope is outside the creating staff member's own grants

Related pages

• API contract: /docs/operator-api/api-keys
• current session introspection: /docs/operator-api/session