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.

FeldTypPflichtBeschreibung
jobs:readscopeOptionalRead jobs, titles, locations and status
jobs:writescopeOptionalCreate, edit jobs and change status (draft/online/archived)
applications:readscopeOptionalRead applications, status history and details
applications:writescopeOptionalSubmit applications, change status, add notes
candidates:readscopeOptionalRead candidate profiles, contact data and CV data
candidates:writescopeOptionalEdit candidate profiles (permitted fields only)
settings:readscopeOptionalRead company settings, offices and pipeline stages
settings:writescopeOptionalCreate, edit and delete offices
talent_pool:readscopeOptionalRead Talent Pool entries and ratings
talent_pool:writescopeOptionalAdd and remove candidates from Talent Pool
calendar:readscopeOptionalRead interviews, appointments and calendar entries
analytics:readscopeOptionalRecruiting 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