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. 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 sk_live_xxxxxxxxxxxxxxxxxxxx

Example Request

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

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"
  }
}