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

# Authentication

> How Lucent ingest keys and Data API bearer tokens are validated.

Lucent uses different credentials for write-only ingest and bearer-token Data
API access.

| API        | Credential                                                | Where to use it                                        |
| ---------- | --------------------------------------------------------- | ------------------------------------------------------ |
| Ingest API | `luc_pk_...` public key                                   | `X-Lucent-Api-Key` header or `api_key` query parameter |
| Data API   | `luc_api_...` API key or `luc_oat_...` OAuth access token | `Authorization: Bearer ...` header                     |

## Ingest public keys

All requests to the Lucent ingest API are authenticated with a **public key**
issued from your dashboard. Public keys begin with `luc_pk_` and are scoped to a
single organization. They are **write-only** — they can submit session data but
cannot read anything back, which is why it is safe to embed them in client-side
JavaScript.

## Key format

```text theme={null}
luc_pk_7a4f9e2b6c1d3f...
```

Create and revoke keys at **Settings → SDK keys** in [app.lucenthq.com](https://app.lucenthq.com).

### Passing the key

Lucent accepts the key in either an HTTP header *or* a query parameter. The
header is preferred; the query parameter exists so that `navigator.sendBeacon`
requests (which cannot set custom headers) can still authenticate on page
unload.

<Tabs>
  <Tab title="HTTP header (preferred)">
    ```http theme={null}
    POST /api/sdk/replay HTTP/1.1
    Host: batch-jobs-lucent.onrender.com
    Content-Type: application/json
    X-Lucent-Api-Key: luc_pk_...
    ```
  </Tab>

  <Tab title="Query parameter (sendBeacon fallback)">
    ```http theme={null}
    POST /api/sdk/replay?api_key=luc_pk_... HTTP/1.1
    Host: batch-jobs-lucent.onrender.com
    Content-Type: application/json
    ```
  </Tab>
</Tabs>

### Ingest error responses

<ResponseField name="401 Unauthorized">
  * `{"error": "Missing API key"}` — no `X-Lucent-Api-Key` header or `api_key`
    query parameter was supplied.
  * `{"error": "Invalid or revoked API key"}` — the key is not recognized or
    has been revoked in the dashboard.
</ResponseField>

<ResponseField name="429 Too Many Requests">
  Rate limit exceeded. The response includes a `Retry-After` header with the
  number of seconds until the limit resets.
</ResponseField>

### Ingest rate limits

Each API key is limited to **100 requests per minute** per key, using a
sliding‑window algorithm. With the SDK's default batching settings
(`flushIntervalMs: 10_000`), a single browser session produces roughly 6
requests per minute — well under the limit.

If you build a custom server‑side integration that aggregates many sessions
through a single key, you may need multiple keys or a higher tier. Contact
[support@lucenthq.com](mailto:support@lucenthq.com) if you run into limits.

### CORS

The ingest API responds with `Access-Control-Allow-Origin: *`, so you can call
it from any browser origin. The following headers are allowed on requests:

* `Content-Type`
* `Content-Encoding` (for gzipped bodies)
* `X-Lucent-Api-Key`

Preflight `OPTIONS` requests are handled automatically and require no special
client configuration.

## Data API bearer tokens

The [Data API](/api-reference/data-api) uses API keys and OAuth bearer tokens
for reading data and updating issue status.

```http theme={null}
GET /api/v1/issues HTTP/1.1
Host: app.lucenthq.com
Authorization: Bearer luc_api_...
```

Supported token types:

* `luc_api_...` — an API key created in **Organization settings → MCP**
* `luc_oat_...` — an OAuth access token

Legacy static keys with the `luc_mcp_` prefix continue to work.

Bearer tokens are scoped to the organization that created or authorized them.
You cannot override the organization with a request parameter.

### Data API scopes

| Scope          | Allows                              |
| -------------- | ----------------------------------- |
| `read:lucent`  | Read issues, signals, and insights. |
| `write:issues` | Update issue status.                |

API keys default to `read:lucent`. When creating an API key, enable **Allow
issue status updates** to add `write:issues`. OAuth clients must request the
scopes they need; unknown scopes are rejected.

### Data API error responses

<ResponseField name="401 Unauthorized">
  `{"error": "Missing or invalid bearer token"}` — no bearer token was supplied,
  the token prefix is not supported, the token was revoked, or the token is
  unknown.
</ResponseField>

<ResponseField name="403 Forbidden">
  `{"error": "Missing required scope: write:issues"}` — the bearer token is
  valid but does not include the scope required by the endpoint.
</ResponseField>

`401` responses include this challenge header:

```http theme={null}
WWW-Authenticate: Bearer scope="read:lucent"
```

For write endpoints, the challenge uses `scope="write:issues"`.