Authentication
Understand how requests are authenticated in both directions.
API Keys
All authenticated requests to /v1/* endpoints require a Polyscout API key passed using the Authorization header.
Authorization: Bearer <POLYSCOUT_API_KEY>API keys are issued to a builder profile and represent the identity of an integrating platform. A single API key can be used to manage multiple wallets and strategies on behalf of many end users.
The API key is not scoped to a single wallet. Instead, it authenticates the builder integration itself, while wallets, strategies, place bets, and executions are scoped internally by wallet and user context. This allows all execution volume generated through the integration to be attributed to the same builder profile.
API keys are generated through the Polyscout Telegram bot using the /api command. When a key is created, it is shown once and should be stored securely by the integrating platform.
Key Scope and Permissions
An API key has the same permissions as the builder profile that generated it. Using this key, an integration can:
Register and manage multiple wallets
Configure local or remote signing for those wallets
Create, update, start, and stop strategies
Create and manage place bets
Read executions and execution history
The API key does not grant direct custody over funds. All trade execution still requires valid wallet signatures and follows the configured signing flow.
Key Rotation
API keys can be rotated at any time using the API. Rotation immediately invalidates the previous key.
The new key is returned once in the response. Integrations should update stored credentials immediately after rotation. Using idempotency when rotating keys is recommended to avoid accidental double rotations.
Invalid or Missing Keys
If a request is missing the Authorization header or the API key is invalid, the API returns a 401 UNAUTHORIZED response.
If the key is valid but the request attempts an action that is not permitted, the API returns 403 FORBIDDEN.
Security Notes
API keys should be treated as sensitive credentials. They should never be embedded in client-side applications or exposed publicly. For production use, keys should be stored in a secure secrets manager or environment variables.
If an API key is compromised, it should be rotated immediately.
Last updated