Authentication & Scopes
All API requests are authenticated via API keys. Keys are issued per tenant and have granular scope control.
API Key Types
AeroSelect distinguishes between two key types:
- Live Keys (
ak_live_...) — Access to production data. Use for all real integrations. - Test Keys (
ak_test_...) — Access to test data. Perfect for development without affecting production data.
Protect your keys
API keys grant direct access to your data. Never store them in version control (Git), frontend code or client-side applications. Always use environment variables.
Request Format
Add the API key as the X-API-Key header to every request:
Bash
curl https://api.aeroselect.io/api/v2/external/jobs \
-H "X-API-Key: ak_live_••••••••••••••••" \
-H "Accept: application/json"api-client.jsJavaScript
const headers = {
"X-API-Key": process.env.AEROSELECT_API_KEY,
"Accept": "application/json",
"Content-Type": "application/json",
};
const response = await fetch(
"https://api.aeroselect.io/api/v2/external/jobs",
{ headers }
);All Available Scopes
Scopes are set when creating an API key in AeroSelect. A key can have multiple scopes. Only grant the scopes your integration actually needs.
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| jobs:read | scope | Optional | Read jobs, titles, locations and status |
| jobs:write | scope | Optional | Create, edit jobs and change status (draft/online/archived) |
| applications:read | scope | Optional | Read applications, status history and details |
| applications:write | scope | Optional | Submit applications, change status, add notes |
| candidates:read | scope | Optional | Read candidate profiles, contact data and CV data |
| candidates:write | scope | Optional | Edit candidate profiles (permitted fields only) |
| settings:read | scope | Optional | Read company settings, offices and pipeline stages |
| settings:write | scope | Optional | Create, edit and delete offices |
| talent_pool:read | scope | Optional | Read Talent Pool entries and ratings |
| talent_pool:write | scope | Optional | Add and remove candidates from Talent Pool |
| calendar:read | scope | Optional | Read interviews, appointments and calendar entries |
| analytics:read | scope | Optional | Recruiting statistics, conversion rates and reports |
Key Rotation
Rotate API keys regularly — at least every 90 days. If you suspect a leak:
- Navigate in AeroSelect to Settings → API Keys
- Click on the affected key and select "Revoke key"
- Immediately create a new key and update your environment variables
- Review the API logs for unauthorized access
Key Management
You can create multiple API keys per tenant — for example one key per integration or environment (staging vs. production). Each key has an independent scope and can be revoked individually.
Error for Invalid Key
For an invalid or missing key, the API responds with:
401 UnauthorizedJSON
{
"message": "Unauthenticated.",
"errors": {}
}For a key without the required scopes:
403 ForbiddenJSON
{
"message": "This action is unauthorized.",
"errors": {
"scope": ["Required scope 'jobs:write' is not granted for this API key."]
}
}Security Best Practices
- Always use environment variables
- Create separate keys with minimal scopes per integration
- Enable IP allowlisting for critical integrations
- Enable the API key audit log in AeroSelect for compliance
- Rotate keys after engineering staff changes