Participant sessions API

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

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	Description
`external_user_id` required	body	string	Your own stable ID for the user. Max 255 characters.
`display_name`	body	string	Name shown to the participant. Max 255 characters.
`username`	body	string	Max 255 characters. Used by profile quests.
`email`	body	string	Max 255 characters. Used by profile quests and for the winner email.
`phone`	body	string	Max 32 characters. Used by profile quests.
`avatar_url`	body	string	Max 2048 characters.
`locale`	body	string	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	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	IANA timezone. Max 64 characters.
`host_context`	body	object	Version 1 host profile context. Max 8192 encoded bytes.
`location`	body	object	Location permission context, such as {"status":"granted","latitude":35.6892,"longitude":51.389}.
`push`	body	object	Push permission context, such as {"status":"granted","token":"push-token"}.
`capabilities`	body	object	Permission map. Each of profile, location, push and custom is granted, denied or unavailable.

Request, cURL

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"
}'

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

Response 200

{
  "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"
    }
  }
}

401 The Secret Key is missing or wrong.

Response 401

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

422 A field failed validation.

Response 422

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

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

Response 429

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

Participant sessions guideA backend helper, refresh, logout and host context.

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

Create a participant session using the host-selected SDK language