Authentication & request signing

The Survey Feed API uses two credentials, both found in the Publisher Dashboard under your app's Settings tab → API settings:

1. API token — identifies your app. Required on every request.
2. API Secret — used to compute and verify signatures. Never sent in a request.

API token

Your API token is required on every Survey Feed API endpoint. Send it in a header:

Header	Description
X-Api-Token	Identifies your app.

A missing or invalid token returns 401.

User identifiers

/players/impanel and /campaigns also need to know which participant the request is for:

Header	Required	Description
X-User-Identifier	Yes	Your unique, stable participant identifier.
X-Device-Identifier	Optional	Hardware/device ID for multi-device distinction.

Using the API secret

Your API secret is never transmitted. It's used to compute or verify signatures for:

1. Impanel security hash — the sech you send to /players/impanel (below)
2. Redirect signing — the sech on post-survey redirects (Redirect URLs)
3. Postback signing — the signature on reward postbacks (Handling rewards)

Security hash

The security hash verifies authenticity for /players/impanel.

How to generate

1. Concatenate the X-User-Identifier value and the current Unix timestamp with a colon. Example: 123e4567-e89b-12d3-a456-426614174000:1713456789
2. Compute the HMAC-SHA256 of that string, keyed with your API secret.
3. Send the following as request params (not headers):
   • sech: the hex-encoded HMAC digest
   • ts: the same Unix timestamp used in the payload
4. Hashes expire after 5 minutes.

Ruby example

require "openssl"

api_secret = "26dcc0fc7b6208fdfeffaf19f627cb4a" # example secret
user_identifier = "123e4567-e89b-12d3-a456-426614174000"
timestamp = Time.now.to_i

payload = "#{user_identifier}:#{timestamp}"
digest = OpenSSL::HMAC.hexdigest("SHA256", api_secret, payload)