OAuth Client Debugging

Overview

Datasources that connect to external platforms (Shopify, Salesforce, Google, Instagram, etc.) authenticate using OAuth client configurations. When a Datasource fails to fetch data, the root cause is often an OAuth issue — expired credentials, a misconfigured token URL, or a broken chain of authentication steps. The OAuth debugging endpoints let you inspect the health of an OAuth client, test token acquisition without affecting live data, clear stale cached tokens, and preview the outgoing authentication request. Each endpoint is designed for safe, non-destructive use in production. All calls require an access token — see Authentication for how to obtain one.

These diagnostic endpoints never store tokens. Every test is strictly a dry run — it verifies the flow and discards the result. Your live Datasource configuration is never modified.

OAuth client status

The status check gives you a snapshot of an OAuth client’s current health. Use it as the first diagnostic step when a Datasource reports authentication errors.

curl -XGET https://api.reelevant.com/v2/datasources/oauth/<auth_id>/status \
  -H "Authorization: Bearer <access_token>"

Example response

{
  "status": "success",
  "data": {
    "id": "665f1c0b2a9d4e0008b3a1f2",
    "mode": "refresh_token",
    "hasRefreshToken": true,
    "hasAccessToken": false,
    "hasPassword": false,
    "tokenUrl": "https://accounts.google.com/o/oauth2/token",
    "scopes": ["offline_access", "https://www.googleapis.com/auth/analytics.readonly"],
    "cachedToken": {
      "exists": true,
      "ttlSeconds": 1842
    },
    "chain": {
      "hasNext": false
    },
    "configuration": {
      "type": "company-scoped",
      "clientId": "123456789.apps.googleusercontent.com"
    }
  }
}

Response fields

Field	Description
id	The unique identifier of the OAuth client.
mode	The authentication mode — `password`, `client_credentials`, `refresh_token`, `access_token`, `custom_payload`, or `jwt_bearer`.
hasRefreshToken	Whether a refresh token is stored (boolean).
hasAccessToken	Whether an access token is stored (boolean).
hasPassword	Whether a password is stored (boolean).
tokenUrl	The URL used to request tokens from the external platform.
scopes	The list of permission scopes requested during authorisation.
cachedToken	Whether a cached token exists and its remaining time-to-live in seconds.
chain	Whether this client is chained to another OAuth client, and if so, the chained client’s identifier and mode.
configuration.type	Whether the configuration is `company-scoped` or `global`.
configuration.clientId	The OAuth client identifier registered with the external platform.

Interpreting the results

Start by checking the credential booleans. The expected values depend on the authentication mode:

Mode	Expected credentials
`refresh_token`	hasRefreshToken = true
`access_token`	hasAccessToken = true
`password`	hasPassword = true
`client_credentials`	Credentials are in the configuration itself (clientId + clientSecret).
`custom_payload`	Credentials are embedded in the custom payload template.
`jwt_bearer`	The signing key is stored in the clientSecret field of the configuration.

If the expected credential boolean is false, the OAuth callback likely did not complete successfully. Re-run the authorisation flow for that Datasource.

The hasRefreshToken, hasAccessToken, and hasPassword booleans also appear in the standard OAuth client listing. You do not need the status endpoint to see them — any response that includes an OAuth client will show these fields.

Test token (dry-run)

The test token endpoint executes the full token acquisition flow and reports each step with its outcome, duration, and diagnostic detail. It is the most powerful debugging tool — it tells you exactly which step failed and why.

curl -XPOST https://api.reelevant.com/v2/datasources/oauth/<auth_id>/test-token \
  -H "Authorization: Bearer <access_token>"

How it works

The endpoint runs through up to seven steps, stopping at the first failure:

Step	What it checks
resolve_auth	Verifies the OAuth client configuration is populated. Reports the mode, configuration type, and whether a chain exists.
check_credentials	Validates that the required credentials are present for the authentication mode (see the table above).
build_request	Constructs the token request. Reports the target URL, the method, and the body fields that will be sent.
send_request	Sends the token request to the external platform. Reports whether a token was received.
parse_response	Validates that the response contains a usable access token.
resolve_chain	(Only for chained configurations.) Looks up the next OAuth client in the chain and verifies it exists.
chain_request	(Only for chained configurations.) Runs the full test token flow recursively on the chained client, nesting its own step trace inside this step.

Example response — successful client_credentials flow

{
  "status": "success",
  "data": {
    "success": true,
    "steps": [
      {
        "name": "resolve_auth",
        "status": "success",
        "durationMs": 1,
        "detail": {
          "mode": "client_credentials",
          "configType": "company-scoped",
          "hasChain": false
        }
      },
      {
        "name": "check_credentials",
        "status": "success",
        "durationMs": 0,
        "detail": {
          "hasClientId": true,
          "hasClientSecret": true
        }
      },
      {
        "name": "build_request",
        "status": "success",
        "durationMs": 0,
        "detail": {
          "method": "GET",
          "url": "https://api.partner.com/oauth/token",
          "bodyFields": ["grant_type", "client_id", "client_secret"]
        }
      },
      {
        "name": "send_request",
        "status": "success",
        "durationMs": 245,
        "detail": {
          "hasTokenAcquired": true
        }
      },
      {
        "name": "parse_response",
        "status": "success",
        "durationMs": 0,
        "detail": {
          "tokenFound": true
        }
      }
    ]
  }
}

Example response — expired refresh token

{
  "status": "success",
  "data": {
    "success": false,
    "steps": [
      {
        "name": "resolve_auth",
        "status": "success",
        "durationMs": 1,
        "detail": {
          "mode": "refresh_token",
          "configType": "company-scoped",
          "hasChain": false
        }
      },
      {
        "name": "check_credentials",
        "status": "success",
        "durationMs": 0,
        "detail": {
          "hasRefreshToken": true
        }
      },
      {
        "name": "build_request",
        "status": "success",
        "durationMs": 0,
        "detail": {
          "method": "GET",
          "url": "https://accounts.google.com/o/oauth2/token",
          "bodyFields": ["grant_type", "refresh_token", "client_id", "client_secret"]
        }
      },
      {
        "name": "send_request",
        "status": "failed",
        "durationMs": 312,
        "detail": {
          "httpStatus": 401,
          "responseBody": "{\"error\": \"invalid_grant\"}"
        },
        "error": "Token request failed with status 401"
      }
    ]
  }
}

The refresh token has been revoked or has expired. Re-authorise the Datasource to obtain a new refresh token.

Example response — chained configuration failure

Some OAuth setups use chained authentication, where the first OAuth client’s token is fed into a second client. The test token endpoint handles this automatically — the chained client’s step trace is nested inside the chain_request step.

{
  "status": "success",
  "data": {
    "success": false,
    "steps": [
      {
        "name": "resolve_auth",
        "status": "success",
        "durationMs": 1,
        "detail": {
          "mode": "client_credentials",
          "hasChain": true
        }
      },
      {
        "name": "check_credentials",
        "status": "success",
        "durationMs": 0,
        "detail": { "hasClientId": true, "hasClientSecret": true }
      },
      {
        "name": "build_request",
        "status": "success",
        "durationMs": 0,
        "detail": { "method": "GET", "url": "https://auth.partner.com/token" }
      },
      {
        "name": "send_request",
        "status": "success",
        "durationMs": 198,
        "detail": { "hasTokenAcquired": true }
      },
      {
        "name": "parse_response",
        "status": "success",
        "durationMs": 0,
        "detail": { "tokenFound": true }
      },
      {
        "name": "resolve_chain",
        "status": "success",
        "durationMs": 2,
        "detail": {
          "chainedAuthId": "665f1c0b2a9d4e0008b3a1f3",
          "chainedMode": "custom_payload"
        }
      },
      {
        "name": "chain_request",
        "status": "failed",
        "durationMs": 450,
        "detail": {
          "chainedSteps": [
            {
              "name": "resolve_auth",
              "status": "success",
              "durationMs": 1,
              "detail": { "mode": "custom_payload", "hasChain": false }
            },
            {
              "name": "build_request",
              "status": "failed",
              "durationMs": 0,
              "error": "Missing required variable in custom payload template"
            }
          ]
        },
        "error": "Chained token acquisition failed at build_request"
      }
    ]
  }
}

The primary client authenticated correctly, but the chained client failed at the build_request step. Inspect the nested chainedSteps to identify the exact failure in the second client.

Chained configurations are common with platforms that require a two-stage authentication process — for example, obtaining a platform token first, then exchanging it for a data-access token with a different provider.

Invalidate cache

Reelevant caches access tokens to avoid requesting a new token on every Datasource refresh. The cache uses a time-to-live based on the token’s expiration. In some cases, the cached token may become invalid before its TTL expires — for example, when the external platform revokes it.

curl -XPOST https://api.reelevant.com/v2/datasources/oauth/<auth_id>/invalidate-cache \
  -H "Authorization: Bearer <access_token>"

Example response — cache existed

{
  "status": "success",
  "data": {
    "cacheKey": "test-client-id-a1b2c3d4-665f1c0b2a9d4e0008b3a1f2-access-token",
    "deleted": true
  }
}

Example response — no cache

{
  "status": "success",
  "data": {
    "cacheKey": "test-client-id-a1b2c3d4-665f1c0b2a9d4e0008b3a1f2-access-token",
    "deleted": false
  }
}

Field	Description
cacheKey	The internal cache key that was targeted.
deleted	`true` if a cached token was found and removed; `false` if no cached token existed.

After invalidation, the next Datasource refresh will request a fresh token from the external platform.

This endpoint requires update permission on the OAuth client (not just read). If you receive a 404, verify that your access token has write access to the Datasource.

Preview request

For OAuth clients using custom_payload or jwt_bearer mode, the authentication request is constructed dynamically from a template with variable substitution. The preview request endpoint shows you the fully interpolated request — exactly what would be sent to the external platform — without actually sending it.

curl -XPOST https://api.reelevant.com/v2/datasources/oauth/<auth_id>/preview-request \
  -H "Authorization: Bearer <access_token>"

Example response

{
  "status": "success",
  "data": {
    "method": "POST",
    "url": "https://auth.partner.com/oauth2/token",
    "headers": {
      "Content-Type": "application/x-www-form-urlencoded",
      "Authorization": "Basic ****"
    },
    "body": {
      "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
      "assertion": "****"
    },
    "mode": "jwt_bearer"
  }
}

Field	Description
method	The request method (`GET` or `POST`).
url	The fully constructed token URL.
headers	The request headers after variable substitution, with secret values masked as `****`.
body	The request body after variable substitution, with secret values masked as `****`.
mode	The authentication mode (`custom_payload` or `jwt_bearer`).

Use this to verify that variable placeholders (such as {{clientId}} or {{jwt}}) are being replaced correctly and that the request structure matches the external platform’s requirements.

The preview endpoint only works for custom_payload and jwt_bearer modes. For other modes it returns a 400 error, since those modes use standard OAuth flows that do not construct a custom request.

Callback diagnostics

When a user completes the OAuth authorisation flow (clicking “Authorise” in the Datasource wizard), the callback page now shows diagnostic information if something goes wrong.

Success

On a successful callback, the page displays a confirmation message and can be closed.

Failure

On failure, the callback page displays:

Field	Description
Error	The type of failure — for example, `token_mismatch` when the expected token type was not returned.
Mode	The authentication mode of the OAuth client.
Hint	A human-readable suggestion for resolving the issue.

A token_mismatch error typically means the external platform returned an access token when a refresh token was expected (or vice versa). Check that the OAuth scopes include offline_access or the platform-specific equivalent for obtaining refresh tokens.

Debugging workflow

A recommended sequence for diagnosing a failing Datasource authentication:

Check the status

Call GET /oauth/<auth_id>/status to verify credentials are present and check whether a cached token exists.If hasRefreshToken, hasAccessToken, or hasPassword is unexpectedly false, re-authorise the Datasource.

Run a dry-run test

Call POST /oauth/<auth_id>/test-token to execute the full token acquisition flow. Read the step trace to identify the first failing step.Common failures:

send_request with status 401 → expired or revoked credentials
build_request failure → misconfigured request template
chain_request failure → issue in the chained OAuth client

Invalidate the cache if needed

If the test token succeeds but the Datasource still fails, the issue may be a stale cached token. Call POST /oauth/<auth_id>/invalidate-cache to clear it.

Preview the request (custom modes)

For custom_payload or jwt_bearer modes, call POST /oauth/<auth_id>/preview-request to inspect the fully interpolated request and compare it with the external platform’s documentation.

Common issues and solutions

Symptom	Likely cause	Recommended action
Datasource fails with “authentication error”	Expired or revoked token	Run test-token to identify the failing step. If `send_request` fails with a 401, re-authorise the Datasource.
hasRefreshToken is false after authorisation	OAuth callback did not receive a refresh token	Check the scopes — ensure `offline_access` (or the platform equivalent) is included. Re-authorise.
Test token succeeds but Datasource still fails	Stale cached token	Invalidate the cache, then trigger a Datasource refresh.
`custom_payload` mode returns unexpected errors	Incorrect variable substitution in the request template	Use preview-request to inspect the interpolated request and compare it with the platform’s documentation.
Chained configuration fails at `chain_request`	The second OAuth client in the chain has a configuration issue	Expand the nested `chainedSteps` in the `chain_request` step to find the failure. Fix the chained client, then re-test.
Callback page shows `token_mismatch`	The platform returned a different token type than expected	Verify the OAuth scopes and the platform’s token exchange behaviour. Some platforms require specific scopes to return refresh tokens.
404 on `invalidate-cache`	Insufficient permissions	This endpoint requires update permission. Verify your access token has write access to the Datasource.

Authentication — obtaining an access token to call the Datasources API.
Special Configurations — OAuth integration setup, API keys, and other advanced Datasource configurations.
Logs — monitoring Datasource execution history.
Source Types — configuring different Datasource source types.

Getting Started

DataHub Deep Dive

Advanced Workflows

Email Rendering

Transformations

Advanced Analytics

Overview

OAuth client status

Example response

Response fields

Interpreting the results

Test token (dry-run)

How it works

Example response — successful client_credentials flow

Example response — expired refresh token

Example response — chained configuration failure

Invalidate cache

Example response — cache existed

Example response — no cache

Preview request

Example response

Callback diagnostics

Success

Failure

Debugging workflow

Common issues and solutions

​Overview

​OAuth client status

​Example response

​Response fields

​Interpreting the results

​Test token (dry-run)

​How it works

​Example response — successful client_credentials flow

​Example response — expired refresh token

​Example response — chained configuration failure

​Invalidate cache

​Example response — cache existed

​Example response — no cache

​Preview request

​Example response

​Callback diagnostics

​Success

​Failure

​Debugging workflow

​Common issues and solutions

​Related pages

Overview

OAuth client status

Example response

Response fields

Interpreting the results

Test token (dry-run)

How it works

Example response — successful client_credentials flow

Example response — expired refresh token

Example response — chained configuration failure

Invalidate cache

Example response — cache existed

Example response — no cache

Preview request

Example response

Callback diagnostics

Success

Failure

Debugging workflow

Common issues and solutions

Related pages