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

# Authentication

# Authentication

Lucitra Validate uses API keys for programmatic access and Stytch B2B session tokens for dashboard users. This page covers how authentication works, rate limits, enterprise tier gating, and debugging tools.

## API Keys

API keys are the primary authentication method for the REST API, CLI, and MCP server. Generate keys from your dashboard at [validate.lucitra.ai](https://validate.lucitra.ai) under **Settings > API Keys**.

All API keys use the `luci_` prefix and are passed as Bearer tokens in the `Authorization` header:

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.lucitra.io/v1/datasets \
    -H "Authorization: Bearer luci_your_api_key"
  ```

  ```python python theme={null}
  import requests

  response = requests.get(
      "https://api.lucitra.io/v1/datasets",
      headers={"Authorization": "Bearer luci_your_api_key"},
  )
  ```

  ```javascript javascript theme={null}
  const response = await fetch("https://api.lucitra.io/v1/datasets", {
    headers: {
      Authorization: "Bearer luci_your_api_key",
    },
  });
  ```
</CodeGroup>

<Warning>
  API keys grant full access to your organization's data. Never commit keys to version control, embed them in client-side code, or share them in plaintext. Use environment variables or a secrets manager.
</Warning>

### Key Management

* Keys can be created and revoked from the dashboard at any time
* Each key is scoped to a single organization
* Revoking a key takes effect immediately -- all in-flight requests using that key will be rejected
* There is no way to retrieve a key after creation; store it securely when generated

## Rate Limiting

All API keys are subject to rate limits to ensure platform stability.

| Parameter | Value                    |
| --------- | ------------------------ |
| Window    | 60-second sliding window |
| Limit     | 100 requests per window  |
| Scope     | Per API key              |

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 12 seconds.",
    "retry_after": 12
  }
}
```

<Tip>
  The response includes a `Retry-After` header with the number of seconds to wait. Implement exponential backoff in production clients rather than retrying immediately.
</Tip>

Rate limit headers are included on every response:

| Header                  | Description                              |
| ----------------------- | ---------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed in the window   |
| `X-RateLimit-Remaining` | Requests remaining in the current window |
| `X-RateLimit-Reset`     | Unix timestamp when the window resets    |

## JWT Sessions (Dashboard)

The Lucitra Validate dashboard uses Stytch B2B session tokens for user authentication. These are managed automatically by the web application and are not required for API-only usage.

<Note>
  If you are only using the REST API, CLI, or MCP server, you do not need to interact with JWT sessions. API keys are sufficient for all programmatic access.
</Note>

Dashboard sessions use short-lived JWTs issued by Stytch, with automatic refresh. Session tokens are scoped to the authenticated user's organization and respect role-based access controls configured in the dashboard.

## Enterprise Tier Gating

Certain endpoints are restricted to organizations on the Enterprise tier. Attempting to access these endpoints on a free or standard plan returns a `403 Forbidden` response with the `ENTERPRISE_REQUIRED` error code.

Gated capabilities include:

| Capability            | Endpoints              |
| --------------------- | ---------------------- |
| Compliance engine     | `/v1/compliance/*`     |
| Audit trail           | `/v1/audit/*`          |
| Provenance tracking   | `/v1/provenance/*`     |
| Model cards           | `/v1/model-cards/*`    |
| Certification reports | `/v1/certifications/*` |

```json theme={null}
{
  "error": {
    "code": "ENTERPRISE_REQUIRED",
    "message": "This endpoint requires an Enterprise tier subscription.",
    "upgrade_url": "https://validate.lucitra.ai/settings/billing"
  }
}
```

<Info>
  Contact [sales@lucitra.ai](mailto:sales@lucitra.ai) or visit your billing settings to upgrade to Enterprise.
</Info>

## Request IDs

Every API response includes an `X-Request-Id` header containing a unique identifier for that request. Include this ID when contacting support or filing bug reports.

```
X-Request-Id: req_7f3a2b1c4d5e6f
```

<Tip>
  Log `X-Request-Id` values in your application. When debugging issues, the Lucitra support team can trace the full request lifecycle using this identifier.
</Tip>

### Extracting the Request ID

<CodeGroup>
  ```bash curl theme={null}
  curl -v https://api.lucitra.io/v1/datasets \
    -H "Authorization: Bearer luci_your_api_key" 2>&1 | grep X-Request-Id
  ```

  ```python python theme={null}
  response = requests.get(
      "https://api.lucitra.io/v1/datasets",
      headers={"Authorization": "Bearer luci_your_api_key"},
  )
  request_id = response.headers.get("X-Request-Id")
  print(f"Request ID: {request_id}")
  ```

  ```javascript javascript theme={null}
  const response = await fetch("https://api.lucitra.io/v1/datasets", {
    headers: { Authorization: "Bearer luci_your_api_key" },
  });
  const requestId = response.headers.get("X-Request-Id");
  console.log(`Request ID: ${requestId}`);
  ```
</CodeGroup>

## Security Best Practices

<CardGroup cols={2}>
  <Card title="Rotate Keys Regularly" icon="arrows-rotate">
    Generate new API keys periodically and revoke old ones. This limits the blast radius if a key is compromised.
  </Card>

  <Card title="Use Environment Variables" icon="lock">
    Store keys in environment variables or a secrets manager. Never hardcode keys in source files.
  </Card>

  <Card title="Monitor Usage" icon="chart-line">
    Review API usage in the dashboard to detect unexpected spikes that may indicate a leaked key.
  </Card>

  <Card title="Scope Access" icon="user-shield">
    Use separate API keys for different environments (development, staging, production) and services.
  </Card>
</CardGroup>