Authentication and Scopes
Send the partner key in every request:
x-api-key: sw_tip_your_key
Keys are shown once when issued. Store the key in a server-side secret manager or encrypted environment variable. Never embed it in browser JavaScript, a mobile bundle, a public repository, logs, analytics, or support screenshots.
Treat each key as a bearer credential for one partner integration. Do not share a key with another protocol. A shared key will technically work from both systems, but both systems will appear as the same partner, use the same scopes, share one rate-limit bucket, and produce combined usage logs. Request a separate key for every protocol or integration. If a key is shared or exposed, rotate it immediately.
Scopes
| Scope | Access |
|---|---|
tip:tokens:read | Token search and core token data. |
tip:analysis:read | Stored Token Analysis state and data. Required by profile and batch endpoints. |
tip:history:read | Metadata history when history is explicitly requested. |
tip:metadata:submit | Reserved for a future metadata submission API. |
Endpoint requirements:
| Endpoint | Required scopes |
|---|---|
| Search | tip:tokens:read |
| Single profile | tip:tokens:read, tip:analysis:read |
| Batch profiles | tip:tokens:read, tip:analysis:read |
| Any request including history | Base endpoint scopes plus tip:history:read |
Authentication failures
Missing keys return 401 API_KEY_REQUIRED. Malformed, unknown, expired, or revoked keys return 401 API_KEY_INVALID. Missing scopes return 403 INSUFFICIENT_SCOPE.
Owner administrators can update the scopes on an active key in Admin Control without rotating it. The key value, expiration, rate limit, and any unedited scopes are preserved.
Partner authentication fails closed. If the authentication store cannot be verified, the API returns 503 PARTNER_AUTH_UNAVAILABLE and does not expose profile data.
Synthwav Portal API access never grants token metadata editing rights. Token Authority and Steward permissions are verified separately through the TIP editor.
Rotation and revocation
Keys have an expiration date and can be rotated or revoked by SynthwavLabs. Rotation invalidates the previous key and produces a new secret. Applications should support replacing the key without code changes.