cliodotDocsMain site
Sign inStart building
OAuth Apps

OAuth Apps API reference

Reference base URLs, server credentials, response envelopes, errors, and enum values.

PrerequisitesOAuth Apps overview

All paths below are relative to your Cliodot API host (for example https://api.cliodot.com).

Prefix Example
/oauth https://api.cliodot.com/oauth/apps/{appId}/connect

Authentication#

Server-to-Server API#

Authenticate with credentials issued when your OAuth App is created in the Cliodot portal (app_api_key prefix oak_) or the app ID + secret pair.

Option A — API key (recommended)

Header Value
Authorization Bearer YOUR_APP_API_KEY

Option B — App ID + secret

Header Value
X-Cliodot-App-Id oauth_app_507f1f77bcf86cd799439011
X-Cliodot-App-Secret YOUR_APP_SECRET

Store app_secret and app_api_key securely. They are shown only at app creation and credential rotation in the portal.

Public Connect and Callback#

No authentication. These endpoints are rate-limited per IP.

Response Envelope and Errors#

Success responses#

Most endpoints return JSON with "ok": true and a resource payload:

{
  "ok": true,
  "connection": { }
}

Connect and callback endpoints may return 302 redirects instead of JSON (see Connect and Callback).

Error responses#

{
  "ok": false,
  "error": "Human-readable error message",
  "code": "OAUTH_EXCHANGE_CODE_INVALID"
}
Field Description
ok Always false on error
error Human-readable message
code Machine-readable error code from Error Codes (when applicable)

HTTP status codes follow REST conventions (400 validation, 401 unauthorized, 403 forbidden, 404 not found, 409 conflict, 422 unprocessable, 428 pending, 502 upstream provider failure).

Error Codes#

Error codes you may encounter in connect, callback, token exchange, and connection flows:

Code HTTP Description
OAUTH_APP_NOT_FOUND 404 OAuth app not found or invalid appId
OAUTH_PROVIDER_NOT_CONFIGURED 404 Provider alias is not attached to the app
OAUTH_APP_DISABLED 403 OAuth app is disabled
OAUTH_PROVIDER_DISABLED 403 Attached provider is disabled
OAUTH_REDIRECT_URI_NOT_ALLOWED 400 redirect_uri is not in the app's allowlist
OAUTH_SCOPE_NOT_ALLOWED 400 Requested scopes violate scope policy or provider catalog
OAUTH_STATE_INVALID 400 Missing, expired, or replayed OAuth/SAML state or device poll state
OAUTH_EXCHANGE_CODE_INVALID 400 Exchange code is invalid, expired, or already consumed
OAUTH_CREDENTIALS_MISSING 422 OAuth client or SAML credentials are not configured on the provider
OAUTH_PROVIDER_ERROR 502 Third-party authorization, token, or userinfo request failed
OAUTH_CONNECTION_REVOKED 409 Connection was revoked and cannot be used
OAUTH_CONNECTION_EXPIRED 404 Ephemeral connection expired or not found
OAUTH_UNAUTHORIZED_APP 401 Invalid or missing app API key or app secret
OAUTH_CONNECTOR_INVALID 404 Connector is missing or does not support the required OAuth protocol

Consumer-relevant field values you will encounter in connect, token exchange, and connection responses:

Field Values
Connection status active, expired, revoked, error
connection_storage persistent, ephemeral
token_exposure_policy metadata_only, include_access_token, include_refresh_token
scope_policy connector_default, extended, custom
oauth.grant_type authorization_code, client_credentials, refresh_token, urn:ietf:params:oauth:grant-type:device_code, urn:ietf:params:oauth:grant-type:jwt-bearer, urn:ietf:params:oauth:grant-type:saml2-bearer, urn:ietf:params:oauth:grant-type:token-exchange