Integration API Key Security

Overview

Survanta provides integration API keys that allow external systems and developer tools to access tenant data programmatically. This page explains what API keys are, how they are scoped, and how to keep them secure.

What Is an API Key?

An integration API key is a secret credential that an external application presents to the Survanta API to identify the tenant and the level of access granted. API keys are generated and managed by Tenant Admins within the Survanta dashboard.

Scope and Access Level

Integration API keys provide read-only access through exactly three case-sensitive scopes, subject to the tenant plan:

• ReportsRead — survey metadata and aggregate response summaries
• UsageRead — integration usage summary
• RawResponsesRead — raw response metadata and current file descriptors/downloads; answer values are not exposed by the current DTO

API keys do not grant:

• Write access (create, modify, or delete surveys, users, or settings)
• Access to another tenant's data
• Dashboard administrator capabilities
• Platform Admin capabilities

Every request made with an API key is restricted to the tenant that issued the key and to the scopes the key was configured with.

Generating an API Key

Authorized Tenant Admin paths use the TenantIntegrationClients dashboard surface:

1. Open the tenant integration-client list.
2. Choose Create.
3. Give the key a descriptive name (for example, "Analytics Dashboard Integration" or "CRM Sync").
4. Select the scopes and a mandatory future expiry within the configured maximum. RawResponsesRead uses the shorter lifetime bound.
5. Create the client.
6. Copy the key immediately — it is shown in full only once.

After closing the generation dialog, you can no longer retrieve the full key value. If you lose the key, you must generate a new one.

Keeping API Keys Secure

API keys should be treated like passwords. Follow these guidelines:

• Never commit an API key to source control (version control systems such as Git). Even private repositories can be accidentally made public.
• Store keys in environment variables or a secrets manager, not in application source code or configuration files checked into a repository.
• Do not share keys in email, chat, or any other non-secure channel.
• Use one key per integration — this way, if one key needs to be rotated, other integrations are not affected.
• Rotate keys periodically as a precaution, even if no compromise is suspected.

Rotating a Compromised Key

If you suspect an API key has been exposed or misused:

1. Open the tenant integration-client list.
2. Locate the compromised key.
3. Use Rotate to replace the key while retaining the client/scopes, or Revoke to disable the client.
4. Copy any replacement from its one-time no-cache view and update the consuming system.

There is no waiting period — revocation takes effect instantly.

Monitoring API Key Usage

Administrators can review the paged client audit log. Each successfully authenticated request updates LastUsedAt and writes an ApiCall entry with endpoint, IP address, and user-agent metadata. This occurs before endpoint scope enforcement.

Frequently Asked Questions

Can I give an API key write access? The current integration endpoints are read-only; no integration-key write contract is exposed.

What happens to data accessed via a compromised key? Revoking the key stops any further unauthorized access. Data that may have already been read cannot be "un-read." Review your API access logs to understand the scope of any exposure.

Can I restrict an API key to specific IP addresses? No IP-allowlist field or enforcement rule exists in the current integration client contract. IP addresses are captured as audit metadata only.