# Authentication

> The credentials AdQuest uses, which request each one goes on, and where it may be stored.

Source: https://dashboard.adquest.batriders.ir/docs/authentication · Audience: Developers · Section: Build

## Credentials at a glance

| Credential | Sent as | Used by | May appear in |
| --- | --- | --- | --- |
| Public API key (aqk_) | X-AdQuest-Platform-Key header | Widget, SDK client, browser requests | Browser code. It is public. |
| Secret Key (aqs_) | X-AdQuest-Platform-Secret header | Your backend, to create participant sessions | Your server only. Never in a browser, app bundle or URL. |
| Participant token | X-AdQuest-Participant-Token header | The widget or client, for one user | The signed-in user’s browser or WebView. It expires. |
| Webhook secret | Verifies X-AdQuest-Signature | Your webhook receiver | Your server only. |

The publisher creates the keys in the dashboard. Keys and environments lists what to ask for.

## Create a participant session

Call this from your backend after you have verified who the user is.

**Request**

```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": "user_123", "display_name": "Ada" }'
```

**Response**

```json
{
  "status": true,
  "code": "OK",
  "message": "Participant session created",
  "data": {
    "participant_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.EXAMPLE.SIGNATURE",
    "expires_at": "2026-01-01T12:15:00+00:00",
    "expires_in": 900
  }
}
```

The response also includes platform_user, eligibility and locale_resolution. The token lasts 15 minutes. Return participant_token and the expiry to that user’s frontend.

## Call the API as a participant

**Request**

```bash
curl "https://api.adquest.batriders.ir/api/v1/platform/quests?external_user_id=user_123" \
  -H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
  -H "X-AdQuest-Participant-Token: TOKEN_FOR_THIS_USER"
```

The React widget and the headless client send these headers for you.

## Rules to follow

> **Warning: The Secret Key stays on your server.** Anyone who has it can create participant sessions for any user. Never send it to a browser, an app bundle or a URL.

- Keep the Secret Key on your server. If it leaks, rotate it in the dashboard. The old one keeps working for 24 hours.
- Use an opaque, stable user ID from your own system as external_user_id.
- Create one participant token per user. Refresh it before it expires and discard it on logout.
- A dashboard login token is not a participant token and will be rejected.
- If the publisher limits where AdQuest may appear, your app’s origin must be on that list, or browser requests are refused.

- [Participant sessions](https://dashboard.adquest.batriders.ir/docs/participant-sessions): Backend helper, refresh, logout and host context.
- [Errors](https://dashboard.adquest.batriders.ir/docs/errors): What each error code means.