> ## 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.

# Server events

> Send track and identify events from your backend to POST /v0/events with the project secret key.

Send events from your backend when the browser or the game is not the right place: a webhook handler, a background job, a Cloudflare Worker or a game server. Server events go to the same endpoint as web and game events, `POST /v0/events`. Each event has `channel: 'server'`, and the request uses the project **secret key**.

## Create the secret key

1. Open your project and go to **Settings > General > Credentials**.
2. Click **Create secret key**. You must be an owner or admin with an [MFA](https://docs.manalens.dev/security/mfa.md) session.
3. Copy the key. It starts with `ua_sk_` and is shown **only once**. ManaLens stores only a SHA-256 hash and a short display prefix.

You can rotate the key (the old key stops working at once) or revoke it in the same place. Each change is in the [audit log](https://docs.manalens.dev/security/roles.md) (`project.secret_key_created`, `project.secret_key_rotated`, `project.secret_key_revoked`).

> [!WARNING]
>
> The secret key is for your backend only. Never put it in a web page, a game build or an app build. Keep it in a server-side secret store. A request with an `Origin` header (a browser) and a secret key is refused with `403` `SECRET_KEY_FROM_BROWSER`.

The [publishable key](https://docs.manalens.dev/api/authentication.md#publishable-key) cannot send server events, and the secret key cannot send web or app events. See [authentication](https://docs.manalens.dev/api/authentication.md).

## Send events

Send the secret key as `Authorization: Bearer`. Do not send an `x-publishable-key` header in the same request.

```bash theme={null}
curl -X POST https://api.your-domain.com/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","properties":{"sku":"dlc_1"},"context":{"ip":"203.0.113.7","user_agent":"Mozilla/5.0 ..."}}]}'
# {"accepted":1}
```

```ts Node.js theme={null}
await fetch('https://api.your-domain.com/v0/events', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ANALYTICS_SECRET_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    events: [
      { channel: 'server', type: 'identify', user_id: 'player_123',
        anonymous_id: '3f0c5c1e-8a8e-4c1b-9d7e-2b1f4e6a9c10',
        traits: { email: 'ada@example.com', plan: 'pro' } },
      { channel: 'server', type: 'track', event: 'invoice_sent', user_id: 'player_123',
        properties: { amount: 120 } },
    ],
  }),
});
```

See the [API reference](https://docs.manalens.dev/api/events.md#server-events) for every field and response.

## Rules

* Every event in the batch has `channel: 'server'`. A batch that mixes server events with web or app events gets `400` `MIXED_CHANNELS`.
* Types are `track` and `identify` only.
* Up to **100** events in one request, and at most **256 KB**.
* `user_id` alone is enough. You can also send `anonymous_id`, or both.
* `message_id` and `original_timestamp` are optional. Old timestamps are allowed, so you can backfill. A timestamp more than 5 minutes in the future is refused.
* Server events have their own rate limit bucket, so browser traffic does not use up the quota of your backend.

## Context

The request comes from your backend, so its IP address and user agent are not the player's. The collector does not use the request IP or the request user agent for server events. Your backend can forward the player's values in `context`:

| Field | What the collector does |
| - | - |
| `ip` | IPv4 or IPv6. Used only for an in-memory country lookup. Never stored or logged. |
| `user_agent` | Parsed to device, OS and browser. A bot user agent gets device `bot`, and reports exclude it. The raw value is never stored. |
| `country` | ISO alpha-2 code. Wins over the country from `ip`. Without both, the country is `ZZ` (unknown). |
| `device` | `desktop`, `mobile` or `tablet`. Wins over the value from `user_agent`. |
| `os`, `browser` | Win over the values from `user_agent`. |
| `locale` | For example `en-US`. |
| `page` | `{ path, title, url }`, all optional. |
| `app` | The same object as on [app events](https://docs.manalens.dev/sdks/app-events.md#the-app-context): `platform`, `storefront`, `app_version`, `build`, `engine`. With a native platform, the OS and device come from the platform. |
| `library_name`, `library_version` | The name and version of your server code. |

All context fields are optional.

## Join server events to players

* **`user_id` only:** the event gets a stable project-scoped ID, so the user counts as one visitor.
* **`anonymous_id` only:** forward the ID of the browser or game (`analytics.getAnonymousId()` in the web SDK) to join the event to that visitor.
* **Both:** the event links that browser or game to the user, so earlier anonymous activity joins the user's profile.

## Session ID of the client

Send the session ID of the client with your server call. The event is then in the visitor's [session](https://docs.manalens.dev/data/metrics.md#sessions), also when your backend sends it late (for example after a payment webhook, hours or a day later). A server event adds its event and revenue to the session and does not change the session duration: the duration comes from the events that the website or the game sent.

1. The client reads its two IDs and sends them with its request to your backend: `getAnonymousId()` and `getSessionId()` in the [web SDK](https://docs.manalens.dev/sdks/web.md#sessions) and the [Node SDK](https://docs.manalens.dev/sdks/node.md) app mode, `get_anonymous_id()` and `get_session_id()` in [Godot](https://docs.manalens.dev/sdks/godot.md), `AnonymousId` and `SessionId` in [Unity](https://docs.manalens.dev/sdks/unity.md).
2. Your backend puts them on the event as `anonymous_id` and `session_id`.

```bash theme={null}
curl -X POST https://api.your-domain.com/v0/events \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"events":[{"channel":"server","type":"track","event":"purchase","user_id":"player_123","anonymous_id":"3f0c5c1e-8a8e-4c1b-9d7e-2b1f4e6a9c10","session_id":"7a1e2c44-91d0-4f5e-b6a3-0c2d9e8f7a61","properties":{"revenue":9.99,"currency":"USD"}}]}'
```

* A `session_id` needs the `anonymous_id` of the same client: a session belongs to one `anonymous_id`.
* A server event **without** a `session_id` stays valid. It joins the session of the same `anonymous_id` that is active at that time, or one that starts in the next 30 minutes. If there is none, the event is in no session that counts. It still counts as an event and as revenue.
* The rule that an event needs a session ID is for website and game events (the publishable key). It does not apply to server events.

## Retries

Set a `message_id` (a UUID) on each event. If you send the same event twice, reports count it once. If you omit it, the collector creates one.

## Errors

| Status | Code | Cause |
| - | - | - |
| `202` | | `{"accepted": n}` |
| `400` | `INVALID_EVENT` | A field is not valid, or a timestamp is too far in the future |
| `400` | `MIXED_CHANNELS` | The batch mixes server events with web or app events |
| `401` | `UNAUTHORIZED` | The key is missing or not valid, the secret key is in `x-publishable-key`, or the request sends both headers |
| `403` | `SECRET_KEY_FROM_BROWSER` | The request has an `Origin` header |
| `403` | `SECRET_KEY_REQUIRED` | Server events were sent with the publishable key |
| `403` | `WORKSPACE_SUSPENDED` | The workspace is suspended |
| `413` | `TOO_LARGE` | The body is larger than 256 KB |
| `429` | `RATE_LIMITED` | Too many events. Wait for `Retry-After` |

See [errors](https://docs.manalens.dev/api/errors.md) for the full list.

## Reports

Server events appear in every event report, on profiles, in the Users list, retention, funnels and breakdowns. Their origin `channel` is `server`. They have no acquisition channel, so channel reports show them as Direct.


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