Security Rules for Integration API Consumers
Following these rules protects the tenant's survey data and reduces the risk of unauthorized access through compromised integration keys.
1. Store Keys in Secrets Management Systems
Never store an API key in:
- Source code or version control (even private repositories).
- Configuration files committed to a repository.
- Client-side JavaScript, mobile app binaries, or any code shipped to end users.
- Plain-text files on shared drives or wikis.
Store keys in:
- Environment variables injected at deployment time.
- A secrets manager such as Azure Key Vault, AWS Secrets Manager, HashiCorp Vault, or an equivalent system.
- CI/CD pipeline secrets stores (not in pipeline YAML files themselves).
2. Grant Minimum Required Scopes
Request only the scopes the integration actually needs. If the integration reads aggregate reports only, request ReportsRead only — do not request UsageRead or RawResponsesRead "just in case."
This limits the data exposure if a key is compromised.
3. Rotate Keys Regularly
Establish a rotation schedule appropriate for your organization's security policy (for example, every 90 days). The Tenant Admin performs rotation in the Tenant Admin dashboard.
Coordinate a short cutover window with the consuming system. Rotation invalidates the old key immediately and reveals the replacement only after the rotation action, so the current contract provides no overlap in which both keys are valid.
4. Rotate Immediately After Suspected Compromise
If a key may have been exposed — for example, accidentally logged, committed to a repository, or sent via an insecure channel — rotate it immediately. The old key is invalidated the moment rotation is confirmed.
After rotation, audit logs of the consuming system to check whether the key was used by unauthorized parties during the exposure window.
5. Do Not Share Keys Across Systems
Each consuming system or integration should have its own integration client and key. This allows individual keys to be rotated or revoked without affecting other integrations.
6. Use HTTPS Only
All Integration API requests must use HTTPS. Never send API keys over plain HTTP.
7. Validate Responses on Your Side
The Integration API returns only data belonging to the tenant whose key was used. However, validate the surveyId and other identifiers in responses against your own records to detect any unexpected data.
8. Handle 429 Responses Correctly
Implement exponential backoff and respect Retry-After when present after HTTP 429. The current integration service supports active/revoked state but does not document automatic or temporary key suspension as a rate-limit consequence.
9. Do Not Log Full Key Values
Ensure that your integration code, infrastructure logs, and monitoring systems do not capture the full X-Survanta-Api-Key header value. If logging is required for debugging, log only the key prefix.