Step 1: Authentication Workflow

You will need Research Desk account credentials to authenticate. To call the Demand API, that user must have the Demand API user access toggle enabled. The Admin role on its own no longer grants a user access to the API. An Admin grants the toggle in Research Desk Admin settings.

The Research Desk Demand API leverages email-password combinations to authenticate API access, and utilizes JSON Web Tokens (JWT) to authorize each API call. This authorization standard enables developers to build fully secure applications, easily manage access, and provide better experiences for end users. Prior to implementing authentication and authorization, please read the following sections to determine the workflow which best fits your needs. Hybrid workflows are common, such as a user-facing application passing authentication credentials from a browser while storing a set of credentials server-side to authenticate API calls powering a recurring job.

External End-User Authentication

Although rare, there are cases in which integrations directly leverage the Research Desk Demand API authentication and authorization system to manage external end users. In this case, the external user’s email address and password should be passed directly from the browser to the Research Desk Demand API. Once authenticated, the returned token should be stored in a browser cookie, along with the given expiration. When a user action warrants an API call, the expiration stored in the cookie should be validated and the token is directly passed into the authorization header of the API call. If the expiration has passed, the user should be prompted to re-enter their email address and password, creating a new token which can then overwrite the previously stored token. When an end user wishes to terminate their session, the token value and timestamp stored in the browser cookie should be destroyed; there is no API action necessary.

Internal User Authentication

For applications which are exposed to users within your company, single sign-on (SSO) integrations are highly recommended. The Research Desk Demand API supports Security Assertion Markup Language (SAML) based single sign-on authentication and authorization. This method of authentication enables companies to manage user access to the API using their consolidated system of choice, and prevents credential exposure. To obtain certificates and additional information, please contact your Rep Data account manager. If your company does not leverage SSO, internal users’ browser sessions can be authenticated and authorized in the same method as the recommended external end-user workflow detailed above. Internal users may also leverage their email address and password combinations to authenticate via non-custom applications such as Postman.

WorkOS AuthKit Tokens

Authorized Demand API requests also accept WorkOS AuthKit access tokens for organizations that authenticate through WorkOS. Pass the AuthKit JWT in the Authorization header the same way as a token from POST /tokens; the Bearer prefix is optional. Notes:

POST /tokens continues to issue Cognito JWTs from email/password credentials only
WorkOS AuthKit tokens are obtained from your WorkOS AuthKit login flow, not from POST /tokens
The API validates Cognito first, then WorkOS AuthKit if Cognito validation fails

Server-to-Server Authentication

Credentials can be created, stored, and leveraged on the back-end of any application. It is highly recommended to create separate credentials for disparate categories of functionality, such as one set of credentials used as a proxy for end-user activity and a separate set used to authorize API calls necessary for a recurring job or alerting system. Once a token is generated using a set of credentials, the expiration should be stored and validated prior to executing any API calls.

Machine Credentials

Backend integrations can be issued a machine credential instead of storing a person’s email address and password. Rep Data provisions a client ID, a client secret, and the token URL for your environment. Your backend exchanges them for an access token using the OAuth 2.0 client credentials grant, and passes that token in the Authorization header with the Bearer prefix, as OAuth 2.0 clients conventionally do.

curl -X POST "$TOKEN_URL" \
  -d grant_type=client_credentials \
  -d client_id="$CLIENT_ID" \
  -d client_secret="$CLIENT_SECRET"

The response carries the access token and its lifetime. Store the expiration and refresh before it passes, as with any other token. Every request made with a machine credential acts as one Research Desk user: the person named in the X-RepData-Acting-User header, or the integration user configured for the credential when that header is absent. Each credential is tied to a single Research Desk account, and a request sees and changes only what its user may within that account.

Acting on Behalf of a Person

Send the person’s work email address in the X-RepData-Acting-User header. The request is authorized as that person, limited to what they may reach, and the audit record names them.

curl -X GET https://demand.researchdesk.com/surveys \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-RepData-Acting-User: jane.doe@example.com" \
  -H "Content-Type: application/json"

The address has to belong to an active Research Desk user in your organization, with Demand API access and access to the credential’s account. If it does not, the request is refused with 403 and is never served as somebody else, so a misspelled address fails loudly rather than acting as the wrong person.

Acting Without Naming a Person

Omit the header to act as the integration user configured for your credential. Recurring jobs, alerting, and other work that is not on behalf of a particular person belong here. Such a request reaches whatever that integration user reaches, and the audit record names it with no acting person beside it. Not every credential has an integration user. Where yours does not, every request has to name a person, and one that omits the header is refused with 403.

Rotating a client secret does not change your client ID, and two secrets can be valid at once, so a secret can be rolled without downtime.

Security Best Practices

Treat your Research Desk credentials with the same care as a private key. Anyone with access to your credentials can make API calls under your account.

Credential Hygiene

Create separate credentials for each environment (staging vs. production) and each functional category (user-proxy vs. automated jobs)
Rotate credentials every 90 days as a standard practice, or immediately upon any suspected exposure
Deactivate compromised credentials immediately by contacting your Rep Data account manager or clientsuccess@repdata.com

Token Storage

Never store tokens or credentials in source code or version control
Store credentials in environment variables or a secrets management tool (e.g., AWS Secrets Manager, HashiCorp Vault, Azure Key Vault)
Track token expiration timestamps — tokens are valid for 12 hours. Refresh before expiry rather than re-authenticating on every call

Making Authenticated Requests

Pass a Cognito token from POST /tokens, a WorkOS AuthKit access token, or a machine credential’s access token in the Authorization header of each request. The Bearer prefix is optional: Authorization: <token> and Authorization: Bearer <token> are both accepted.

const token = process.env.RESEARCH_DESK_TOKEN;

const response = await fetch('https://demand.researchdesk.com/surveys', {
  method: 'GET',
  headers: {
    'Authorization': token,
    'Content-Type': 'application/json'
  }
});

const surveys = await response.json();

import os
import requests

token = os.environ['RESEARCH_DESK_TOKEN']

response = requests.get(
    'https://demand.researchdesk.com/surveys',
    headers={
        'Authorization': token,
        'Content-Type': 'application/json'
    }
)

surveys = response.json()

curl -X GET https://demand.researchdesk.com/surveys \
  -H "Authorization: $RESEARCH_DESK_TOKEN" \
  -H "Content-Type: application/json"

Overview

Integration Guide

API Reference (v1)

External End-User Authentication

Internal User Authentication

WorkOS AuthKit Tokens

Server-to-Server Authentication

Machine Credentials

Acting on Behalf of a Person

Acting Without Naming a Person

Security Best Practices

Credential Hygiene

Token Storage

Making Authenticated Requests

​External End-User Authentication

​Internal User Authentication

​WorkOS AuthKit Tokens

​Server-to-Server Authentication

​Machine Credentials

​Acting on Behalf of a Person

​Acting Without Naming a Person

​Security Best Practices

​Credential Hygiene

​Token Storage

​Making Authenticated Requests

External End-User Authentication

Internal User Authentication

WorkOS AuthKit Tokens

Server-to-Server Authentication

Machine Credentials

Acting on Behalf of a Person

Acting Without Naming a Person

Security Best Practices

Credential Hygiene

Token Storage

Making Authenticated Requests