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

# Authentication

> The keys and tokens for the public interfaces: the publishable key and the secret key for events, API keys with scopes, and OAuth access tokens.

ManaLens has three kinds of key and one kind of token:

* The **publishable key** sends website and game events.
* The **secret key** sends server events from your backend.
* An **API key** reads and manages: the REST API with [scopes](https://docs.manalens.dev/mcp/overview.md#scopes) (for example [profile properties](https://docs.manalens.dev/api/profiles/update-properties.md)) and the [MCP server](https://docs.manalens.dev/mcp/overview.md).
* An **OAuth access token** reads reports through the MCP server.

No credential both sends events and reads data.

| Credential | Format | Secret | Used for | Header |
| - | - | - | - | - |
| Publishable key | `ua_pk_...` (older projects: `ua_...`) | No | `POST /v0/events` (`web` and `app` events), `POST /v0/identify`, `GET /v0/tracking/config` | `X-Publishable-Key` |
| Secret key | `ua_sk_...` | Yes | `POST /v0/events` (`server` events) | `Authorization: Bearer` |
| API key | `ua_api_...` (older keys: `ua_mcp_...`) | Yes | `POST /mcp`; with `profiles:write`, `PUT /v0/projects/{projectId}/profiles/.../properties` | `Authorization: Bearer` |
| OAuth access token | Opaque | Yes | `POST /mcp` | `Authorization: Bearer` |

## Publishable key

The publishable key (called the write key in Segment) identifies one project. It is safe to ship in a page or a game build: every page that loads the SDK contains it. It sends website (`web`) and game (`app`) events. It cannot send server events, and it cannot read data.

New projects get a key that starts with `ua_pk_`. Older projects keep their `ua_...` key, and it keeps working.

### Get the publishable key

Open your project, go to **Settings > General > Credentials**, and copy the **Publishable key**.

### Send it

Send it in the `X-Publishable-Key` header. The SDKs do this for you: the web SDK option is `publishableKey` (snippet attribute `data-publishable-key`), the Godot option is `publishable_key`, and the Unity option is `PublishableKey`.

The old names still work as aliases: the `X-Write-Key` header, the web SDK option `writeKey`, the snippet attribute `data-write-key` and the Godot option `write_key`. Do not send both `X-Publishable-Key` and `X-Write-Key` in one request: the collector returns `401`.

```bash theme={null}
curl -sS https://YOUR_COLLECTOR_ENDPOINT/v0/events \
  -H 'X-Publishable-Key: YOUR_PUBLISHABLE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"events":[...]}'
```

### Extra checks on the publishable key

Because the key is public, the collector also checks where a request comes from:

* A request with an `Origin` header (a browser) must come from the project domain, one of its subdomains, or an [allowed origin](https://docs.manalens.dev/sdks/app-events.md#allowed-origins). Other origins get `403`.
* A web event's page URL must be on the project domain, a subdomain, or a host in the project's [allowed origins](https://docs.manalens.dev/sdks/app-events.md#allowed-origins).
* A request without an `Origin` (a native game) is accepted with the key alone.

Anyone who has the key can send web and app events with any context. Do not use these events for data that must be trusted, such as billing. Use a signed [revenue integration](https://docs.manalens.dev/features/revenue.md) for payments.

### Rotate the publishable key

Owners and admins with a verified [MFA](https://docs.manalens.dev/security/mfa.md) session can rotate the key in project **Settings > General > Credentials**. The old key stops working at once. Update every site and game build that sends events.

The key is public by design and only sends events, so a copied key lets someone send events, not read data. The per-project ingest limit applies to every key.

## Secret key

The secret key sends server events (`channel: 'server'`) to `POST /v0/events` from your backend. It starts with `ua_sk_`. A project has at most one.

* Owners and admins with a verified [MFA](https://docs.manalens.dev/security/mfa.md) session create, rotate and revoke it in **Settings > General > Credentials**.
* It is shown once. ManaLens stores only a SHA-256 hash and a short display prefix.
* When you rotate it, the old key stops working at once.
* Each change is in the audit log: `project.secret_key_created`, `project.secret_key_rotated`, `project.secret_key_revoked`.

```bash theme={null}
curl -X POST https://YOUR_COLLECTOR_ENDPOINT/v0/events \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"events":[{"channel":"server","type":"track","event":"purchase_completed","user_id":"player_123"}]}'
```

> [!WARNING]
>
> Never put the secret key in a page, a game build or an app build. A request with an `Origin` header and a secret key gets `403` `SECRET_KEY_FROM_BROWSER`.

See [server events](https://docs.manalens.dev/sdks/server.md).

### Which key goes where

| Request | Result |
| - | - |
| Web or app events with the publishable key in `X-Publishable-Key` | Accepted |
| Server events with the secret key in `Authorization: Bearer` | Accepted |
| Server events with the publishable key | `403` `SECRET_KEY_REQUIRED` |
| Web or app events with the secret key | `403` `PUBLISHABLE_KEY_REQUIRED` |
| A secret key or an API key in `X-Publishable-Key` | `401` `UNAUTHORIZED` |
| A publishable key in `Authorization` | `401` `UNAUTHORIZED` |
| Both `X-Publishable-Key` and `Authorization` | `401` `UNAUTHORIZED` |
| Both `X-Publishable-Key` and `X-Write-Key` | `401` `UNAUTHORIZED` |

## Key format

New keys have a prefix, a random body and a checksum, like GitHub and Supabase tokens. A secret scanner can match them, and a mistyped key fails before any database lookup.

```text theme={null}
<prefix><body: 43 base62 characters><checksum: 8 base62 characters>
```

* Prefixes: `ua_pk_` (publishable key), `ua_sk_` (secret key), `ua_api_` (API key).
* Base62 alphabet: `0-9A-Za-z`. The body holds more than 256 random bits.
* Checksum: the CRC32 (IEEE, as in zlib) of `<prefix><body>`, written in base62 and padded on the left with `0` to 8 characters.
* Regular expression: `ua_(pk|sk|api)_[0-9A-Za-z]{51}`.

Older keys have no checksum and keep working: publishable keys that start with `ua_` and API keys that start with `ua_mcp_`.

## API keys

An API key reads and manages one project: the REST API and the MCP server. New keys start with `ua_api_`. Older keys that start with `ua_mcp_` keep working. Each key has [scopes](https://docs.manalens.dev/mcp/overview.md#scopes):

| Scope | Gives |
| - | - |
| `analytics:read` | Read aggregate analytics reports and the data schema |
| `dashboards:read` | List and read saved dashboards and charts |
| `attribution:read` | Read conversion and revenue attribution |
| `profiles:read` | Read identified user profiles and traits |
| `query:read` | Run SQL on raw events and preview charts |
| `dashboards:write` | Create, edit, move and delete dashboards and charts. It does not include reading them. |
| `profiles:write` | Set and delete [profile properties](https://docs.manalens.dev/api/profiles/update-properties.md) through the REST API. Keys only: OAuth clients cannot ask for it. |

Owners and admins with a verified MFA session create keys in **Settings**, then **Integrations**, under **API keys**. Scopes are required: you choose at least one scope for each key, and a key has no other access. The key is shown once. See [Create an API key](https://docs.manalens.dev/mcp/overview.md#create-an-api-key).

* Keys are stored only as SHA-256 hashes.
* A key with `query:read`, `dashboards:write` or `profiles:write` acts for the person who created it. It stops working when that person leaves the workspace. When that person's role goes below **editor**, the key keeps only its read scopes.
* Click **Revoke** to disable a key at once.
* An API key cannot send events.

> [!WARNING]
>
> Never put an API key in browser, mobile or game code. Keep it in a server-side secret store or in your MCP client's local config.

## OAuth

MCP clients that support OAuth (such as Claude and ChatGPT) can connect without a key. An owner or admin signs in, chooses one project and the scopes, and the client gets an access token for one hour and a refresh token for 30 days. See [MCP OAuth](https://docs.manalens.dev/mcp/oauth.md).

## Dashboard API

The dashboard uses a private API with your sign-in session. It is not a public API and can change without notice. Do not call it from your own code.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.