Authentication

All API requests are authenticated using API keys passed in the X-API-Key header. API keys are scoped to specific endpoints and tied to your organization.

Creating an API key

API keys are managed in the Ayliea web app by organization Owners and Admins.

Open API key settings

Navigate to Organization Settings and select the API Keys tab.

Create a new key

Click Create Key. Provide a descriptive label (e.g., “Splunk Integration” or “Weekly Report Sync”) and select the scopes this key needs.

Copy the key

The full API key is displayed once after creation. Copy it and store it securely — you cannot retrieve it again.If you lose a key, revoke it and create a new one.

Key format

API keys use the following format:

ayliea_pk_<64 hex characters>

The ayliea_pk_ prefix identifies the key type. The first 8 hex characters after the prefix are stored as a visible identifier so you can tell keys apart in the dashboard.

Using a key

Pass your API key in the X-API-Key header on every request:

curl https://assess.ayliea.com/api/v1/scores \
  -H "X-API-Key: ayliea_pk_a1b2c3d4e5f6..."

Never include API keys in URLs, query parameters, or client-side code. Use the header exclusively.

Scopes

Each API key is granted one or more scopes that control which endpoints it can access. A request to an endpoint that requires a scope not assigned to the key returns a 403 Forbidden response.

Scope	Grants access to
`scores:read`	`GET /api/v1/scores`
`recommendations:read`	`GET /api/v1/recommendations`
`discovery:read`	`GET /api/v1/discovery`
`assessments:read`	`GET /api/v1/assessments`

Create keys with the minimum scopes needed for each integration. A SIEM that only needs scores should not have discovery:read access.

Key storage and security

API keys are hashed with SHA-256 before storage. Ayliea does not store the raw key — only you have it. Best practices:

Store keys in a secrets manager (e.g., AWS Secrets Manager, HashiCorp Vault, or your CI/CD platform’s secret store)
Never commit keys to version control
Use separate keys for separate integrations so you can revoke them independently
Set the narrowest scopes possible on each key

Key rotation

There is no automatic key rotation. To rotate a key:

Create a new key with the same label and scopes
Update your integration to use the new key
Verify the integration works with the new key
Revoke the old key

Both the old and new keys work simultaneously until the old key is revoked, so you can rotate without downtime.

Limits

Constraint	Value
Maximum active keys per organization	25
Key length	`ayliea_pk_` prefix + 64 hex characters (74 characters total)

Revoking a key frees up one slot immediately. Revoked keys cannot be re-activated.

Error responses

Status	Meaning
`401 Unauthorized`	Missing `X-API-Key` header or key not found
`403 Forbidden`	Key does not have the required scope, or API access is not included in your engagement

// Missing or invalid key
{ "error": "Invalid API key" }

// Wrong scope
{ "error": "API key does not have the 'scores:read' scope" }

// API access not enabled
{ "error": "API access is not enabled for this organization. Contact your account team to enable it." }

API Reference

Endpoints

Creating an API key

Key format

Using a key

Scopes

Key storage and security

Key rotation

Limits

Error responses

​Creating an API key

​Key format

​Using a key

​Scopes

​Key storage and security

​Key rotation

​Limits

​Error responses

Creating an API key

Key format

Using a key

Scopes

Key storage and security

Key rotation

Limits

Error responses