Security Options - Research Desk Documentation

Research Defender offers two options for protection against API suppression and link manipulation — a common practice used by respondents attempting to manipulate data to bypass security checks.

V3 — Server-to-Server (GETTOKEN)
V4 — Hashed Validation

V3 offers server-to-server callbacks via the GETTOKEN API, which hides sensitive scores and flags produced by SEARCH and REVIEW behind a server-side response.Workflow

Request a token (client-side)

Make a client-side GETTOKEN call to Research Defender with your publishable key. Launching client-side ensures the respondent’s device information is gathered in the same transaction.

Receive the token

Research Defender returns a unique single-use token (a SHA-256 hash value) in a client-side response.

Call SEARCH or REVIEW (server-side)

Make a server-side SEARCH or REVIEW call that includes the token in the header, along with your private key.

Receive results

Research Defender returns all relevant SEARCH or REVIEW data in a server-side response.

Integration notes

A unique token is required for each transaction — tokens cannot be reused.
GETTOKEN generates between 1 and 10 tokens per call. By default it returns one; request more with the tokens= parameter.
Identity parameters such as rt_sr_pd (panelist ID) and rt_hd_el (hashed email) should be provided on the GETTOKEN call as well as the SEARCH call. These are optional and only apply to customers who know the identity of their respondents.
GETTOKEN is only available on V3 and only via the GET method.

<environment>/api/v3/respondents/get_token/<publishable_key>?tokens=<number_of_tokens>&rt_sr_pd=<panelist_id>&rt_hd_el=<hashed_email>

See the GETTOKEN endpoint.

V4 uses Hashed Validation to validate respondents’ inputs and outputs through an encrypted SHA-256 value. Both the input (parameters) and output (JSON result) can be encrypted.

Available only on V4 of the Respondent Tracking API; existing versions are unaffected.
A validation parameter is required to use this feature.
The client’s private key is used in the encryption.
Currently available for SEARCH only. REVIEW and ACTIVITY work in V4, but the validation feature is not provided for them.

https://prod.rtymgt.com/api/v4/respondents/search/<publishable_key>?<existing_parameters>&validation=<sha-256_converted_parameter_value>

How to build the validation value

Construct the SEARCH URL with your parameters, ending with your private key.
Compute the SHA-256 hash of that string (you can verify with the SHA-256 online tool).
Pass the resulting hash as the validation= parameter on the call.

If the validation parameter provided is invalid, the API returns status_code=406.A working HTML sample that demonstrates validating the hashed values is available on request from Research Defender.

​How to build the validation value

How to build the validation value