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

# Authentication

> Learn how to authenticate with the AlfaOne API

## API Key Authentication

All AlfaOne API endpoints require authentication using an API key. API keys are scoped to a single organization, and all data returned will be filtered to that organization.

### Obtaining an API Key

1. Log in to your AlfaOne admin dashboard
2. Navigate to **Settings → Integrations**
3. Click **Generate API Key**
4. Give your key a descriptive name (e.g., "Production Integration", "Development Testing")
5. Copy and securely store the generated key

<Warning>
  API keys are shown only once at creation. Store them securely in your environment variables or secrets manager.
</Warning>

### Using your API Key

Include your API key in the `x-api-key` header with every request:

```bash theme={null}
curl -X GET "https://alfaone.app/api/v1/assessments" \
  -H "x-api-key: ak_live_your_api_key_here"
```

### API Key Format

AlfaOne API keys follow this format:

| Environment     | Format                     | Example                                    |
| --------------- | -------------------------- | ------------------------------------------ |
| Live/Production | `ak_live_` + 32 characters | `ak_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6` |
| Test/Sandbox    | `ak_test_` + 32 characters | `ak_test_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6` |

## Error Responses

If authentication fails, the API will return one of the following errors:

<ResponseField name="error" type="string">
  Description of the authentication error
</ResponseField>

### Common Authentication Errors

<AccordionGroup>
  <Accordion title="401 - Missing API Key">
    ```json theme={null}
    {
      "error": "API key is required"
    }
    ```

    **Solution:** Include the `x-api-key` header in your request.
  </Accordion>

  <Accordion title="401 - Invalid API Key">
    ```json theme={null}
    {
      "error": "Invalid API key"
    }
    ```

    **Solution:** Verify that your API key is correct and hasn't been mistyped.
  </Accordion>

  <Accordion title="401 - Expired API Key">
    ```json theme={null}
    {
      "error": "API key has expired"
    }
    ```

    **Solution:** Generate a new API key from the Integrations page.
  </Accordion>

  <Accordion title="401 - Revoked API Key">
    ```json theme={null}
    {
      "error": "API key has been revoked"
    }
    ```

    **Solution:** This key has been manually revoked. Generate a new API key.
  </Accordion>
</AccordionGroup>

## Security Best Practices

<CardGroup cols={2}>
  <Card title="Use Environment Variables" icon="shield">
    Never hardcode API keys in your source code. Use environment variables or a secrets manager.
  </Card>

  <Card title="Rotate Keys Regularly" icon="arrows-rotate">
    Periodically rotate your API keys and revoke old ones to minimize security risks.
  </Card>

  <Card title="Use Separate Keys" icon="key">
    Use different API keys for development, staging, and production environments.
  </Card>

  <Card title="Monitor Usage" icon="chart-line">
    Regularly review API usage in your dashboard to detect any unusual activity.
  </Card>
</CardGroup>

## Rate Limiting

API requests are rate limited to ensure fair usage:

| Tier       | Rate Limit           |
| ---------- | -------------------- |
| Standard   | 100 requests/minute  |
| Enterprise | 1000 requests/minute |

When you exceed the rate limit, you'll receive a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Rate limit exceeded. Please try again later."
}
```

<Tip>
  Implement exponential backoff in your integration to gracefully handle rate limiting.
</Tip>