Authentication

Create and manage API keys to authenticate requests to the Ayliea REST API.

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.

1. Open API key settings

   Navigate to Organization Settings and select the API Keys tab.

2. 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.

3. 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:

1. Create a new key with the same label and scopes
2. Update your integration to use the new key
3. Verify the integration works with the new key
4. 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 organization is not on the Enterprise tier

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

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

// Not on Enterprise tier
{ "error": "API access requires the Enterprise plan. Contact [e-mail] to upgrade." }