Skip to main content

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.

Each application belongs to one organization, or to one workspace that is not in an organization. The access token reads only that owner's research data.

Create integration credentials​

The Integrations page is available after Optimal enables Research Data API access.

  • Organization. From the organization admin workspace, open Manage Organization, then Integrations, and create a Research API application. That application reads every workspace in the organization.
  • Workspace without an organization. A workspace admin opens Workspace Settings, then Integrations, and creates a Research API application. That application reads only that workspace. A workspace that belongs to an organization uses the organization 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 can access the research data for the organization or workspace that owns the application. 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.

If a workspace later joins an organization, Optimal deletes that workspace's Research API applications and revokes their access tokens. Create an organization application to continue reading that workspace.

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​

SituationResponseWhat to do
The client ID or secret is invalidThe token endpoint returns 401 with invalid_client.Check the configured credentials or create replacement credentials.
The token request asks for an unsupported scopeThe token endpoint returns 400 with invalid_scope.Request only research_read.
The access token is expired, revoked, missing, or unknownThe 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_readThe 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 enabledToken issuance returns 401 with unauthorized_client. If access is removed after a token is issued, API requests return 403 and the message Research Data API is not enabled.Ask your Optimal account contact to confirm feature access.

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