Authentication
Authenticate with the Auralytik API using API keys and HMAC request signing. Every request must include a valid API key in the X-Api-Key header.
1. API Key Authentication
API keys are created in the Admin > API Keys dashboard. Each key is scoped to a specific client and set of permissions. Include your key in the X-Api-Key header on every request.
Include your API key in the X-Api-Key header:
curl https://api.auralytik.ai/api/v1/evaluations \ -H "X-Api-Key: ak_live_abc123def456ghi789jkl012mno345pq" \ -H "Content-Type: application/json"
Key format
Live keys use the prefix ak_live_ followed by 32 alphanumeric characters.
Example: ak_live_abc123def456ghi789jkl012mno345pq
The full key secret is shown only once
When you create a key, the full secret is displayed a single time. Copy it immediately and store it in a secure vault or environment variable. It cannot be retrieved later -- only rotated. Never expose keys in client-side code, Git repositories, or logs.
2. HMAC Request Signing
All requests made with ak_live_ keys must include an HMAC-SHA256 signature. This prevents replay attacks and ensures request integrity. Two additional headers are required:
| Header | Value |
|---|---|
| X-Signature | Base64-encoded HMAC-SHA256 signature |
| X-Timestamp | Current Unix timestamp in seconds |
Signing steps
Get the current Unix timestamp (seconds since epoch).
Hash the request body with SHA-256 and Base64-encode the result. For requests with no body (GET, DELETE), use the hash of an empty string.
Build the canonical string using this format:
{timestamp}.{METHOD}.{path}.{bodyHash}path is the URL path only (e.g. /api/v1/evaluations), with no query string and no host.
Sign the canonical string with HMAC-SHA256 using your HMAC secret key, then Base64-encode the result. Send this value in the X-Signature header.
Pseudocode
timestamp = current_unix_seconds()
body_hash = base64(sha256(request_body)) # empty string if no body
canonical = f"{timestamp}.{method}.{path}.{body_hash}"
signature = base64(hmac_sha256(hmac_key, canonical))
# Send headers
X-Api-Key: ak_live_...
X-Timestamp: {timestamp}
X-Signature: {signature}curl example
# Variables API_KEY="ak_live_abc123def456ghi789jkl012mno345pq" HMAC_KEY="your-hmac-secret-key" TIMESTAMP=$(date +%s) BODY='' BODY_HASH=$(echo -n "$BODY" | openssl dgst -sha256 -binary | base64) CANONICAL="$TIMESTAMP.GET./api/v1/evaluations.$BODY_HASH" SIGNATURE=$(echo -n "$CANONICAL" | openssl dgst -sha256 -hmac "$HMAC_KEY" -binary | base64) curl https://api.auralytik.ai/api/v1/evaluations \ -H "X-Api-Key: $API_KEY" \ -H "X-Timestamp: $TIMESTAMP" \ -H "X-Signature: $SIGNATURE" \ -H "Content-Type: application/json"
Timestamps expire after 5 minutes
The server rejects any request where X-Timestamp differs from the server clock by more than 300 seconds. Keep your system clock synchronized with NTP.
3. Scopes & Permissions
Each API key is assigned one or more scopes that control which endpoints it can access. Assign the minimum scopes required for your integration.
| Scope | Description |
|---|---|
| evaluations:read | Read evaluation results and scores |
| audio:read | List and view audio file metadata |
| audio:download | Download audio file content |
| audio:write | Upload and manage audio files |
| engagements:read | Read engagement records |
| engagements:write | Create and update engagements |
| conversations:read | Read conversation data and messages |
| voice:read | Read voice bot call records |
| analytics:read | Access analytics and dashboards |
| analytics:export | Export analytics data (CSV, Excel) |
| campaigns:read | Read campaign configurations |
| webhooks:manage | Create, update, and delete webhooks |
| keys:manage | Manage API keys (admin only) |
| usage:read | View API usage and billing metrics |
Principle of least privilege
Only grant the scopes your integration actually needs. You can always add more scopes later without rotating the key.
4. Rate Limiting
Rate limits are applied per API key. When you exceed a limit the API responds with 429 Too Many Requests.
| Tier | Requests / min | Daily limit |
|---|---|---|
| Standard | 300 | 50,000 |
| Premium | 1,000 | 200,000 |
| Enterprise | 5,000 | 1,000,000 |
Rate limit headers
| Header | Description |
|---|---|
| X-RateLimit-Limit | Maximum requests allowed in the current window |
| X-RateLimit-Remaining | Requests remaining in the current window |
| X-RateLimit-Reset | Unix timestamp when the window resets |
| X-RateLimit-RetryAfter | Seconds to wait before retrying (only on 429 responses) |
Implement exponential backoff
When you receive a 429 response, wait for the number of seconds indicated by X-RateLimit-RetryAfter before retrying. Combine with exponential backoff for best results.
5. IP Allowlisting
You can optionally restrict each API key to a set of allowed IP addresses or CIDR ranges. Requests from any other IP will be rejected with 403 Forbidden.
Example: restricting a key to two IPs and one CIDR block
{
"allowed_ips": [
"203.0.113.10",
"198.51.100.25",
"10.0.0.0/16"
]
}IP allowlisting is optional
If no IPs are configured, the key works from any address. We recommend enabling allowlisting for production keys to reduce the blast radius of a compromised secret.
6. Key Rotation
Rotate a key to generate a new secret without changing the key ID, scopes, or IP restrictions. During the 24-hour grace period both the old and new secrets are accepted, giving you time to update all consumers.
Rotate a key via the API:
POST https://api.auralytik.ai/api/v1/api-keys/{id}/rotate
# Response
{
"id": "key_abc123",
"new_secret": "ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"hmac_key": "new-hmac-secret-key",
"old_secret_expires_at": "2026-03-31T14:30:00Z",
"grace_period_hours": 24
}Requires keys:manage scope
The API key used to call the rotation endpoint must have the keys:manage scope. We recommend using a separate admin key for key management operations.
Rotation best practice
Rotate keys on a regular schedule (e.g., every 90 days) and immediately after any suspected compromise. The 24-hour grace period ensures zero-downtime rotation for distributed systems.