FAQ — Integration API
Frequently asked questions for developers and teams consuming the Survanta Integration API.
Q: What can I access with an integration API key?
An integration API key grants read-only access to approved Survanta integration endpoints for your organization's tenant. The specific data available depends on the scopes assigned to your API client when it was created. Current scopes cover report metadata, usage summaries, and raw response rows when explicitly granted.
Q: How do I include my API key in a request?
Include your API key in the X-Survanta-Api-Key header of every Integration API request:
X-Survanta-Api-Key: <your-api-key>
Replace <your-api-key> with the key generated when your API client was created or rotated. The key must be included in all requests — there is no session-based authentication for the integration API.
Q: What are the available scopes?
Scopes authorize read-only endpoints; they do not grant modification access. The supported values are exactly:
- ReportsRead — Read survey metadata and aggregate response summaries.
- UsageRead — Read tenant integration usage summary data.
- RawResponsesRead — Read individual response rows. Grant only when required.
The exact scopes available depend on your organization's plan. Contact your Tenant Admin to review or update the scopes assigned to your API client.
Q: What does a 401 response mean?
A 401 Unauthorized response means API-key authentication did not produce an accepted client. Common causes include:
- The API key is missing from the request header.
- The API key is incorrect or has been rotated.
- The API key belongs to a different organization or environment.
- The client is revoked, inactive, or expired.
Check that the X-Survanta-Api-Key header is present and that your key is valid. If the issue persists, contact your Tenant Admin.
Q: How do I rotate my API key?
API key rotation requires the tenant integration-management permission. To rotate a key:
- Ask your Tenant Admin to navigate to Settings > Integration API in the dashboard.
- Locate the API client whose key you want to rotate.
- Click Rotate Key. A new key is generated immediately.
- The old key is invalidated right away.
Rotation invalidates the old key and reveals the replacement once, so there is no overlap in which both keys work. Coordinate immediate deployment of the new key and use a maintenance window where interruption is unacceptable.
Q: What happens if I exceed my API client limit?
ExternalIntegrationClientLimit caps active, unexpired clients. Creation is blocked at capacity. A downgrade reconciles capacity by retaining the oldest allowed clients and revoking newer excess clients. Request more with a LimitIncrease order at /Tenant/Orders/Create.
Q: Are there rate limits on the API?
Integration controllers use configured IntegrationClient policies, and raw-response reads additionally use IntegrationRawResponses. These are application configuration policies, not plan Limit keys. A rejected request can return 429; respect any retry metadata and use bounded exponential backoff with jitter.
Q: Where can I find the API documentation and available endpoints?
Use the Integration API Key documentation category for authentication, scopes, metadata, reports, raw responses, pagination, errors, rotation, and security. Dashboard client creation requires the tenant integration-management permission; documentation visibility is governed separately by the documentation portal.