Skip to main content
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.
ScopeGrants access to
scores:readGET /api/v1/scores
recommendations:readGET /api/v1/recommendations
discovery:readGET /api/v1/discovery
assessments:readGET /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

ConstraintValue
Maximum active keys per organization25
Key lengthayliea_pk_ prefix + 64 hex characters (74 characters total)
Revoking a key frees up one slot immediately. Revoked keys cannot be re-activated.

​
Error responses

StatusMeaning
401 UnauthorizedMissing X-API-Key header or key not found
403 ForbiddenKey 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 sales@ayliea.com to upgrade." }