Header: X-Survanta-Api-Key

The X-Survanta-Api-Key Request Header

Every request to a protected Integration API endpoint uses the IntegrationApiKey authentication scheme and must include the API key in the X-Survanta-Api-Key HTTP header. This is the only supported method of passing the key; query-string parameters and request body fields are not accepted.

Header Format

X-Survanta-Api-Key: <your-api-key>

Replace <your-api-key> with the full key value that was displayed when the integration client was created or last rotated.

Example: curl

curl -X GET "https://<your-tenant-host>/api/integrations/reports/surveys" \
     -H "X-Survanta-Api-Key: svt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     -H "Accept: application/json"

Example: C# HttpClient

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Survanta-Api-Key", apiKey);
client.DefaultRequestHeaders.Accept.Add(
    new MediaTypeWithQualityHeaderValue("application/json"));

var response = await client.GetAsync(
    "https://<your-tenant-host>/api/integrations/reports/surveys");
response.EnsureSuccessStatusCode();
var json = await response.Content.ReadAsStringAsync();

Example: Python requests

import requests

headers = {
    "X-Survanta-Api-Key": "<your-api-key>",
    "Accept": "application/json",
}
response = requests.get(
    "https://<your-tenant-host>/api/integrations/reports/surveys",
    headers=headers,
    timeout=30,
)
response.raise_for_status()
data = response.json()

What Not to Do

Incorrect approach	Why it fails
Send the key as a JWT Bearer token (`Authorization: Bearer <key>`)	Integration endpoints do not use JWT bearer authentication
Send the key as a query string parameter (`?apiKey=...`)	Query string keys are not supported and may be logged
Send the key in the request body	Not supported; body content is reserved for request payload
Use a cookie session instead of the header	Cookie auth is for dashboard users, not integration clients

How the Server Validates the Header

When the server receives a request with X-Survanta-Api-Key:

The header value is hashed using the same algorithm used at key creation time.
The SHA-256 hash is looked up against TenantApiClient records before tenant query filters can apply.
The client must be active, non-revoked, and have a mandatory future expiry. The tenant, subscription, plan capability, scope, and integration-client quota checks must also pass.
On success, the tenant/scopes are placed in the authenticated principal, LastUsedAt is updated, and an ApiCall audit row records endpoint and request metadata.
A missing, blank, invalid, or unknown key returns HTTP 401 with the same response:

{
  "errorCode": 401,
  "errorMessage": "Authentication is required. Provide valid credentials or a valid API key.",
  "data": null
}

The full key is returned only by the create/rotate result. The client record persists only its SHA-256 hash; administrators must treat the one-time secret view as the only retrieval opportunity.

Case Sensitivity

The header name X-Survanta-Api-Key is treated as case-insensitive by ASP.NET Core's header handling. The key value itself is case-sensitive — pass it exactly as provided.