Authentication

Creating an API Key

1. Go to Organization Settings → API Keys
2. Click "Create API key"
3. Enter a name and optional description
4. Select the required scopes for your integration
5. Choose when the key expires (90 days unless you pick otherwise)
6. Click "Create" and copy your key immediately

Using Your API Key

Include your API key in the Authorization header as a Bearer token:

Authorization: Bearer svt_live_xxxxxxxxxxxxxxxxxxxx

Example Request

curl -X GET "https://app.surventrics.ai/api/v1/surveys" \
  -H "Authorization: Bearer svt_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Key format

Keys start with svt_live_, followed by 38 letters and digits. The last six characters are a checksum, so a mistyped or truncated key is rejected straight away. Keys in the older sk_live_ format are no longer accepted: create a new key, or roll the old one, on the API keys page.

Expiry and rotation

New keys expire after 90 days by default. You can choose 30, 60, 180 or 365 days, a specific date, or no expiry. A key that never expires keeps working until someone revokes it, so use one only where you can't rotate. Requests made with an expired key get 401 with the message API key has expired.

The key's creator and your organization's admins are emailed 7 days before a key expires, 1 day before, and when it expires.

Rolling a key

Roll a key from the API keys page to replace it without downtime. The new key has the same name, scopes and rate limit, and you choose how long the old key keeps working: not at all, 1 hour, 24 hours or 7 days. BI connector endpoints switch to the new key straight away. A key can be rolled once; to rotate again, roll its replacement.

When a key's creator leaves

If the member who created a key leaves your organization, the API refuses every request made with it straight away. A key acts as the member who created it, so those requests get 403 with details.reason actor_not_member, and your admins are emailed. An admin can reassign the key to a current member, which restores it at once with that member's role under a new secret: the admin is shown it once, and the old secret stops working, so give the new one to whoever runs the integration. A key that isn't reassigned within 14 days is disabled.

Members limited to named clients

A request made as a member whose access is limited to named clients (an API key they created, or a hosted MCP sign-in) sees only the surveys of their clients and lists only those clients. Another client's survey answers 404, exactly as a survey that does not exist. Contacts, contact lists, suppressions, email domains, groups, integrations, webhooks, and creating, renaming or deleting folders answer 403 forbidden with error.details.reason restricted_member. Tagging one of their own clients' surveys, or moving it into a folder, works as it does in the app. Folder and tag names stay visible to them, so don't name a folder or tag after a client. Creating a survey must name one of their clients (400 invalid_request, details.reason client_required or client_not_assigned). The key follows the member's current access, so a change takes effect on the next request.

API Scopes

API keys are created with specific scopes that control what actions they can perform. Request only the scopes you need:

Security Best Practices

• Never expose keys in client-side code - API keys should only be used in server-side applications
• Use environment variables - Store keys in environment variables, never in source code
• Rotate keys periodically - Create new keys and revoke old ones regularly
• Use minimal scopes - Only request the scopes you actually need
• Set expiration dates - For temporary integrations, set an expiration date on the key

Error Responses

Authentication errors return a 401 Unauthorized or 403 Forbidden status:

Missing or Invalid Key

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

Insufficient Scope

{
  "error": {
    "code": "forbidden",
    "message": "Missing required scope: surveys:write"
  }
}

Expired Key

{
  "error": {
    "code": "expired_key",
    "message": "API key has expired"
  }
}