title: "Authenticate with an external IdP token (OAuth 2.0 token exchange)" description: Exchange an external identity provider (IdP) access token for a DataRobot access token using OAuth 2.0 token exchange (RFC 8693). The external OAuth developer workflow for inbound OAuth: bring your own IdP (Okta, Microsoft Entra ID, Ping, Auth0) for user authentication to the DataRobot API.

Authenticate to the DataRobot API with an external IdP token¶

With inbound OAuth, you authenticate to the DataRobot API using an access token from your own identity provider (IdP) instead of a DataRobot API key. You exchange your IdP access token for a short-lived DataRobot access token using OAuth 2.0 token exchange (RFC 8693), then send that DataRobot token as a bearer token on API requests. This external OAuth workflow lets your users authenticate with credentials they already have.

This page covers the developer workflow. For the administrator setup (registering a trusted IdP, provisioning, and mapping), see Inbound OAuth.

Prerequisites¶

• An administrator has configured inbound OAuth for your organization or application and given you the token-exchange endpoint.
• You can obtain an OAuth 2.0 access token from your IdP (for example, Okta, Microsoft Entra ID, Ping, or Auth0).
• Your IdP issues access tokens that include the dr.impersonation scope and carry the DataRobot audience (aud) your administrator provides. DataRobot validates both during the exchange; a missing scope or mismatched audience is rejected. See Step 1.
• You have the DataRobot API endpoint for your region (see Retrieve the API endpoint).

Workflow overview¶

1. Get an access token from your IdP.
2. Exchange it for a DataRobot access token.
3. Call the DataRobot API with the DataRobot token.

Step 1: Get an IdP access token¶

Obtain an OAuth 2.0 access token from your IdP using your organization's standard flow (for example, the authorization code flow). The token must be a JWT access token issued by the IdP your administrator registered.

Refer to your IdP's documentation for how to obtain a token. The following sections refer to that token as IDP_ACCESS_TOKEN.

Step 2: Exchange for a DataRobot access token¶

Exchange the IdP token at the token-exchange endpoint. The endpoint is served at your DataRobot application root, not under /api/v2:

Send a POST request with the RFC 8693 token-exchange parameters, form-encoded:

export IDP_ACCESS_TOKEN="YOUR_IDP_ACCESS_TOKEN"

curl --location -X POST \
  "https://YOUR_DATAROBOT_HOST/oauth2/token/ORGANIZATION_ID" \
  --header "Accept: application/json" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  --data-urlencode "subject_token=${IDP_ACCESS_TOKEN}" \
  --data-urlencode "subject_token_type=urn:ietf:params:oauth:token-type:access_token"

import requests

DATAROBOT_HOST = "https://YOUR_DATAROBOT_HOST"
ORGANIZATION_ID = "ORGANIZATION_ID"  # your organization's ID
idp_access_token = "YOUR_IDP_ACCESS_TOKEN"

response = requests.post(
    f"{DATAROBOT_HOST}/oauth2/token/{ORGANIZATION_ID}",
    headers={"Accept": "application/json"},
    data={
        "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
        "subject_token": idp_access_token,
        "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
    },
)
response.raise_for_status()
datarobot_access_token = response.json()["access_token"]

A successful exchange returns a DataRobot access token:

{
  "access_token": "<DATAROBOT_ACCESS_TOKEN>",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "dr.impersonation"
}

Step 3: Call the DataRobot API¶

Send the DataRobot access token as a bearer token, the same as you would a DataRobot API key. Use the /api/v2 endpoint for your region.

export DATAROBOT_ENDPOINT="https://YOUR_DATAROBOT_HOST/api/v2"
export DATAROBOT_ACCESS_TOKEN="DATAROBOT_ACCESS_TOKEN_FROM_STEP_2"

curl --location -X GET "${DATAROBOT_ENDPOINT}/projects/" \
  --header "Authorization: Bearer ${DATAROBOT_ACCESS_TOKEN}"

import datarobot as dr

client = dr.Client(
    endpoint="https://YOUR_DATAROBOT_HOST/api/v2",
    token=datarobot_access_token,  # from Step 2
)
print(dr.Project.list())

Token lifetime¶

DataRobot access tokens from inbound OAuth are short-lived (typically one hour). Read expires_in from the exchange response rather than hard-coding a value. When a token expires, repeat Step 2 to get a new one. Tokens can't be revoked individually.

Error reference¶

The token-exchange endpoint returns errors defined by RFC 6749 and RFC 8693:

{
  "error": "<ERROR_CODE>",
  "error_description": "<ERROR_DESCRIPTION>"
}

FAQ¶

How do I authenticate to the DataRobot API using my Okta or Microsoft Entra ID token?¶

Get an access token from Okta or Microsoft Entra ID, exchange it for a DataRobot access token (Step 2), and call the API with the DataRobot token (Step 3). Your administrator must first register the IdP through Inbound OAuth.

Related¶

• Inbound OAuth—administrator configuration for the trusted IdP, provisioning, and mapping.
• Developer quickstart—API keys, endpoints, and credential setup.