Authorization

Research Data API v1 uses the OAuth 2.0 client credentials flow. This flow is for confidential, server-side integrations that can protect a client secret.

Create integration credentials

An authorized member of your organization's Optimal admin account can open Account > Integrations, then create a Research API application. Optimal displays:

• a client ID; and
• a client secret, shown only when the application is created.

Store the secret in a secrets manager or an encrypted environment variable when it is issued. If the secret is lost or exposed, delete the application and create replacement credentials.

Client credentials identify your organization and can access its research data. Never commit the secret to source control, write it to logs, or embed it in browser code, mobile applications, or other public clients. Public clients cannot keep a client secret confidential and are not supported by this flow.

Request an access token

Set the issued credentials in your shell:

export OPTIMAL_CLIENT_ID='your-client-id'
export OPTIMAL_CLIENT_SECRET='your-client-secret'

Request a token from the production OAuth endpoint. HTTP Basic authentication keeps the credentials out of the form body:

curl --request POST 'https://api.optimalworkshop.com/oauth/token' \
  --user "$OPTIMAL_CLIENT_ID:$OPTIMAL_CLIENT_SECRET" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=research_read'

research_read is the supported scope for Research Data API applications.

A successful response has this shape:

{
  "access_token": "issued-access-token",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "research_read"
}

The access token lasts for one hour. The client credentials flow does not issue a refresh token. Request another access token with the client credentials before the current token expires. Issuing a replacement revokes the previously issued access token for that application.

Call the Research Data API

Send the access token in the Authorization header:

export OPTIMAL_ACCESS_TOKEN='issued-access-token'

curl 'https://api.optimalworkshop.com/api/research/v1/research_activities' \
  --header "Authorization: Bearer $OPTIMAL_ACCESS_TOKEN" \
  --header 'Accept: application/json'

Keep access tokens out of URLs and logs. Treat them as secrets for their full lifetime.

Authorization failures

Situation	Response	What to do
The client ID or secret is invalid	The token endpoint returns 401 with invalid_client.	Check the configured credentials or create replacement credentials.
The token request asks for an unsupported scope	The token endpoint returns 400 with invalid_scope.	Request only research_read.
The access token is expired, revoked, missing, or unknown	The API returns 401 with an unauthorized error and the message Invalid or expired access token.	Request a new token and retry the API request.
A token does not authorize research_read	The API returns 403 with a forbidden error.	Use a token issued to a Research API application with the research_read scope.
Research Data API access is not enabled	Token issuance returns 401 with unauthorized_client. If access is removed after issuance, API requests return 403 and state that the Research Data API is not enabled for the organization.	Ask your Optimal account contact to confirm feature access.

API error responses include a request ID. Include it when contacting Optimal support.