# Participant sessions API

> Create a participant token for one of your signed-in users. Backend only.

Source: https://dashboard.adquest.batriders.ir/docs/api/participant-sessions · Audience: Developers · Section: API reference

## Create a participant session using the host-selected SDK language

### `POST /platform/participant-sessions`

Creates a short-lived participant token for one user of your platform. Call this from your backend only, after you have verified who the user is.

**Authentication:** Secret Key, sent as the X-AdQuest-Platform-Secret header. Backend only.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| external_user_id | body | string | yes | Your own stable ID for the user. Max 255 characters. |
| display_name | body | string | no | Name shown to the participant. Max 255 characters. |
| username | body | string | no | Max 255 characters. Used by profile quests. |
| email | body | string | no | Max 255 characters. Used by profile quests and for the winner email. |
| phone | body | string | no | Max 32 characters. Used by profile quests. |
| avatar_url | body | string | no | Max 2048 characters. |
| locale | body | string | no | Language of the widget: en or fa, region tags such as en-US accepted. Invalid values fall back to English and are never rejected. |
| country_code | body | string | no | Participant’s reward country as an ISO 3166-1 alpha-2 code, such as IR. Null or empty clears it. An unassigned code returns 422. |
| timezone | body | string | no | IANA timezone. Max 64 characters. |
| host_context | body | object | no | Version 1 host profile context. Max 8192 encoded bytes. |
| location | body | object | no | Location permission context, such as {"status":"granted","latitude":35.6892,"longitude":51.389}. |
| push | body | object | no | Push permission context, such as {"status":"granted","token":"push-token"}. |
| capabilities | body | object | no | Permission map. Each of profile, location, push and custom is granted, denied or unavailable. |

```bash
curl -X POST https://api.adquest.batriders.ir/api/v1/platform/participant-sessions \
  -H "Content-Type: application/json" \
  -H "X-AdQuest-Platform-Secret: YOUR_SECRET_KEY" \
  -d '{
  "external_user_id": "player-42",
  "display_name": "Ada",
  "locale": "en-US",
  "country_code": "IR"
}'
```

**Response 200.** The session was created. Return participant_token and its expiry to that user’s frontend. The token lasts 15 minutes.

```json
{
  "status": true,
  "code": "OK",
  "message": "Participant session created",
  "data": {
    "participant_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.EXAMPLE.SIGNATURE",
    "expires_at": "2026-10-24T12:49:08+00:00",
    "expires_in": 900,
    "platform_user": {
      "id": 1,
      "external_user_id": "player-42",
      "display_name": "Ada",
      "avatar_url": null,
      "country_code": null,
      "country_name": null,
      "eligibility_country_code": "IR",
      "eligibility_country_source": "platform"
    },
    "eligibility": {
      "locale": "en",
      "timezone": null,
      "location_permission": "unavailable",
      "push_permission": "unavailable",
      "profile_permission": "unavailable",
      "has_display_name": true,
      "has_avatar": false,
      "has_username": false,
      "has_locale": true,
      "has_timezone": false,
      "has_email": false,
      "has_phone": false,
      "completeness_percent": 28
    },
    "locale_resolution": {
      "requested": "en",
      "effective": "en",
      "source": "host"
    }
  }
}
```

**Response 401.** The Secret Key is missing or wrong.

```json
{
  "status": false,
  "code": "PARTICIPANT_AUTH_REQUIRED",
  "message": "Platform secret is required",
  "data": {
    "code": "PARTICIPANT_AUTH_REQUIRED"
  }
}
```

**Response 422.** A field failed validation.

```json
{
  "status": false,
  "code": "VALIDATION_ERROR",
  "message": "country_code must be an assigned ISO 3166-1 alpha-2 code",
  "data": null
}
```

**Response 429.** Too many session requests. Back off and retry later.

```json
{
  "status": false,
  "message": "Too many session requests",
  "data": {
    "code": "RATE_LIMITED"
  }
}
```

> **Token lifetime.** A participant token lasts 15 minutes. expires_in is 900 and expires_at is the exact time. Create a new session through your backend before it ends.

- [Participant sessions guide](https://dashboard.adquest.batriders.ir/docs/participant-sessions): A backend helper, refresh, logout and host context.