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

# Authentication

> Organization API keys, publishable tracking keys, and how requests are scoped

4D has three credential types. Which one you use depends on where the call is
made from:

| Credential              | Prefix     | Where it lives            | What it's for                                                  |
| ----------------------- | ---------- | ------------------------- | -------------------------------------------------------------- |
| Organization API key    | `org_`     | Your servers (secret)     | The partner REST API: users, imports, key management, webhooks |
| Engagement tracking key | `ek_live_` | Client code (publishable) | `POST /v1/track` browser/app event tracking only               |
| Module credential       | `mk_live_` | Module backends (secret)  | Server-to-server event ingest with HMAC request signing        |

## Organization API keys

Every partner API call authenticates with a bearer header:

```bash theme={null}
curl "$API_BASE_URL/v1/users/$USER_ID" \
  -H "Authorization: Bearer $API_KEY"
```

The key is bound to your organization. There is no org id parameter anywhere
in the API - your key *is* the tenancy. Isolation is enforced with
row-level security at the database layer, so a request can only ever read or
write rows belonging to your organization.

<Warning>
  Treat `org_` keys like passwords: server-side only, never in client bundles,
  rotate if exposed.
</Warning>

## Publishable tracking keys

Browser event tracking can't hide a secret, so it doesn't use one.
`POST /v1/track` authenticates with a **publishable** `ek_live_…` key that
ships in your client code, like an analytics measurement id. Abuse is bounded
by two controls on the key itself, not by secrecy:

* a **per-key origin allowlist** - events are only accepted from browser
  origins you configured for the key;
* **per-key rate limiting**.

You issue and revoke tracking keys with your organization API key - see
[Trigger an event](/walkthroughs/trigger-an-event).

## Module credentials

Installed modules push events server-to-server via `POST /v1/ingest` with an
`mk_live_…` bearer credential plus an HMAC signature header
(`x-4d-signature`) and an `Idempotency-Key`. This surface is only relevant if
you're building a 4D module; module documentation is provided during module
onboarding.

## Error envelope

All authenticated surfaces return errors in one envelope:

```json theme={null}
{
  "error": {
    "code": "UNAUTHORIZED",
    "status": 401,
    "message": "Authentication is required"
  }
}
```

Missing or invalid credentials are a `401`; a valid credential without
permission for the operation is a `403` or, where the resource's existence
shouldn't be revealed, a `404`. `code` values are the stable contract to
program against.