Skip to main content

​
API Key Authentication

All AlfaOne API endpoints require authentication using an API key. API keys are scoped to a single organization, and all data returned will be filtered to that organization.

​
Obtaining an API Key

  1. Log in to your AlfaOne admin dashboard
  2. Navigate to Settings → Integrations
  3. Click Generate API Key
  4. Give your key a descriptive name (e.g., “Production Integration”, “Development Testing”)
  5. Copy and securely store the generated key
API keys are shown only once at creation. Store them securely in your environment variables or secrets manager.

​
Using your API Key

Include your API key in the x-api-key header with every request: 
curl -X GET "https://api.alfaone.com/api/v1/assessments" \
  -H "x-api-key: ak_live_your_api_key_here"

​
API Key Format

AlfaOne API keys follow this format:
EnvironmentFormatExample
Live/Productionak_live_ + 32 charactersak_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
Test/Sandboxak_test_ + 32 charactersak_test_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

​
Error Responses

If authentication fails, the API will return one of the following errors:
​
error
string
Description of the authentication error

​
Common Authentication Errors

{
  "error": "API key is required"
}
Solution: Include the x-api-key header in your request.
{
  "error": "Invalid API key"
}
Solution: Verify that your API key is correct and hasn’t been mistyped.
{
  "error": "API key has expired"
}
Solution: Generate a new API key from the Integrations page.
{
  "error": "API key has been revoked"
}
Solution: This key has been manually revoked. Generate a new API key.

​
Security Best Practices

Use Environment Variables

Never hardcode API keys in your source code. Use environment variables or a secrets manager.

Rotate Keys Regularly

Periodically rotate your API keys and revoke old ones to minimize security risks.

Use Separate Keys

Use different API keys for development, staging, and production environments.

Monitor Usage

Regularly review API usage in your dashboard to detect any unusual activity.

​
Rate Limiting

API requests are rate limited to ensure fair usage:
TierRate Limit
Standard100 requests/minute
Enterprise1000 requests/minute
When you exceed the rate limit, you’ll receive a 429 Too Many Requests response: 
{
  "error": "Rate limit exceeded. Please try again later."
}
Implement exponential backoff in your integration to gracefully handle rate limiting.