> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ayliea.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Steps>
  <Step title="Open API key settings">
    Navigate to **Organization Settings** and select the **API Keys** tab.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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:

```bash theme={null}
curl https://assess.ayliea.com/api/v1/scores \
  -H "X-API-Key: ayliea_pk_a1b2c3d4e5f6..."
```

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

## 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 |

```json theme={null}
// 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." }
```