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

# Join Event

> Register an audience member into the active session and receive their attendee token

Call this endpoint when an audience member joins your show — for example, after they scan the QR code and land on the audience web page. It returns a short-lived `eventToken` scoped to that attendee.

## Endpoint

```
POST /api/v1/runtime/events/{eventId}/join
```

**Auth:** `Authorization: Bearer <accessToken>` (your runtime client token)

| Path param | Description                                                          |
| ---------- | -------------------------------------------------------------------- |
| `eventId`  | The event ID returned by [Start Event](/sdk/runtime-api/start-event) |

## Request body

```json theme={null}
{
  "attendeeRef": "player_42"
}
```

| Field         | Type   | Required | Description                                                                                                                       |
| ------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `attendeeRef` | string | —        | An optional identifier you assign to this attendee (e.g. username, seat number). Used for tracking — not visible to the attendee. |

## Response

```json theme={null}
{
  "eventId": "evt_xxxxxxxxxxxxxxxx",
  "visualId": "vis_xxxxxxxxxxxxxxxx",
  "producerUserId": "usr_xxxxxxxxxxxxxxxx",
  "tokenType": "Bearer",
  "eventToken": "eyJhbGci...",
  "expiresIn": 7200
}
```

| Field        | Description                                                                                                         |
| ------------ | ------------------------------------------------------------------------------------------------------------------- |
| `eventToken` | Attendee-scoped Bearer token. Pass this to the audience web frontend so it can authenticate audience-side API calls |
| `expiresIn`  | Token lifetime in seconds                                                                                           |

## Error responses

| Status | Code                            | Meaning                                      |
| ------ | ------------------------------- | -------------------------------------------- |
| `401`  | `INVALID_RUNTIME_CLIENT`        | Runtime client token missing or invalid      |
| `403`  | `EVENT_NOT_FOUND_OR_ENDED`      | The event doesn't exist or has already ended |
| `403`  | `RUNTIME_CLIENT_NOT_AUTHORIZED` | Token not authorized for this event's visual |

## Typical flow

This call is usually made by the **audience web frontend** (the page your audience visits after scanning the QR code), not directly from Unreal Engine. The frontend calls your visual's backend (or a serverless function you provide), which calls `/join` with the runtime client token and forwards the `eventToken` back to the attendee's browser.

```
Audience scans QR code
    ↓
Audience web page loads → calls your join endpoint
    ↓
Your server: POST /runtime/events/{eventId}/join  { attendeeRef }
    ↓
Returns eventToken to the audience web page
    ↓
Audience web page uses eventToken for all subsequent audience API calls
```