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:

​
API Key Format

AlfaOne API keys follow this format:

​
Error Responses

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

​
Common Authentication Errors

Solution: Include the x-api-key header in your request.
Solution: Verify that your API key is correct and hasn’t been mistyped.
Solution: Generate a new API key from the Integrations page.
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: When you exceed the rate limit, you’ll receive a 429 Too Many Requests response:
Implement exponential backoff in your integration to gracefully handle rate limiting.