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

> ## Agent Instructions
> Reconify's API reference is read-only for customer data. Do not invent endpoints or authentication behavior beyond the OpenAPI contract.
> The public OpenAPI document contains only the external /v1 contract. Dashboard business routes are intentionally excluded.

# Authentication

> Create and use organization API keys.

The public API uses organization-scoped API keys. It does not accept dashboard
sessions or expose customer-data reads.

<Card title="Organization API key" icon="key-round">
  Server-to-server event ingestion. Prefix: `rk_`. Use a write-scoped key.
</Card>

## Create a key

Create and manage keys in **Dashboard → Settings → API Keys**. Only workspace
owners and admins can create, rotate, or revoke keys.

The plaintext secret is shown only once, when the key is created or rotated.
The dashboard can show the key's name and display prefix, but cannot recover the
secret later.

## Send the key

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export RECONIFY_API_KEY="rk_your_key_here"

curl -X POST "https://api.reconifyhq.com/v1/events" \
  -H "Authorization: Bearer $RECONIFY_API_KEY"
```

Scopes:

| Scope   | Use                                                               |
| ------- | ----------------------------------------------------------------- |
| `write` | Submit events to `POST /v1/events`.                               |
| `read`  | No public data reads; reserved for future authenticated surfaces. |
| `admin` | Includes the `write` permission.                                  |

Ingestion requires write authorization. A missing, malformed, expired, revoked,
or wrong-prefix key returns `401 Unauthorized`. A valid key without write scope
returns `403 Forbidden`.

Keys belong to exactly one organization. The API resolves the organization from
the key; callers cannot provide an arbitrary organization ID.

<Warning>
  Store the plaintext key once. It cannot be recovered after creation or rotation.
</Warning>

<Tip>
  Use separate keys for staging and production. Rotate immediately after exposure.
</Tip>

## Security checklist

* Keep keys in a secret manager or runtime environment variable.
* Give each integration its own named key.
* Send keys only in the `Authorization` header over HTTPS.
* Never commit keys or include them in logs, telemetry, tickets, or prompts.
* Rotate a key immediately if it may have been exposed.