Authentication and Request Signing

TapResearch’s Partner API uses two mechanisms to control access and verify request integrity:

1. API Token — identifies your partner account. Only required on endpoints that need authentication.
2. API Secret — used to generate sech signatures for specific flows. Never sent directly in a request.

All Partner API endpoints require your API token for authentication, so this page focuses on when credentials are needed and how request signing works at a high level.

---

API Token

Your API token is required on all Partner API endpoints.

Send it via header:

Header	Description
X-Api-Token	Identifies your partner account.

This header is always required.

---

User Identifiers

For endpoints involving participant context, include the relevant identifiers:

Header	Required	Description
X-User-Identifier	Yes	Unique user or device identifier (UUIDv4).
X-Device-Identifier	Optional	Hardware/device ID for multi-device distinction.

---

Using the API Secret

Your API secret is never transmitted. It is only used to generate signatures (sech) for two flows:

1. Impanel Security Hash (/players/impanel)
2. Redirect Signing (verifying redirect callbacks)

For complete signing instructions, see:

• Security Hash — below
• Redirect Signing

---

Security Hash

The security hash verifies authenticity for /players/impanel.

How to Generate

1. Concatenate user_identifier and Unix timestamp with a colon. Example: 123e4567-e89b-12d3-a456-426614174000:1713456789
2. Compute the SHA-256 HMAC using 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

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