Authentication
Bearer organization API keys, access checks, and error codes.
Credential type
API calls use an organization API key created by an organization owner in Organization settings.
- Key format:
rw_live_… - Send as:
Authorization: Bearer rw_live_… - The organization is determined from the key — do not put org identifiers in the URL for auth
- Creating and rotating keys is limited to organization owners
OAuth for third-party apps may be offered later. Until then, integrations and scripts use API keys.
API access
API access depends on your plan. If your organization is not entitled, the API returns:
{ "error": "…", "code": "PUBLIC_API_NOT_ENTITLED" }
with HTTP 403. Contact support@rankwatch.com or your account manager to discuss access.
Common auth errors
| HTTP | Code | Meaning |
|---|---|---|
| 401 | PUBLIC_API_AUTH_REQUIRED | Missing Bearer token |
| 401 | PUBLIC_API_INVALID_KEY | Unknown or incorrect key |
| 401 | PUBLIC_API_KEY_REVOKED | Key has been revoked |
| 401 | PUBLIC_API_KEY_EXPIRED | Key has expired |
| 403 | PUBLIC_API_NOT_ENTITLED | Plan does not include API access |
| 403 | PUBLIC_API_SCOPE_DENIED | Required scope not granted on this key |
| 403 | PUBLIC_API_WORKSPACE_DENIED | Workspace is outside this key’s allowlist |
Correlation
Responses include a request id in the JSON body and usually as x-request-id. Include it when contacting support.