Cliodot OAuth Apps let you build hosted OAuth integrations without managing token storage, provider callbacks, or PKCE in your own application. Create an OAuth App and attach identity providers (Google, GitHub, custom OAuth templates, SAML IdPs, and more) in the Cliodot portal, then redirect end users through Cliodot's hosted connect flow.
Key security model: Cliodot never returns long-lived access or refresh tokens in browser redirect URLs. After a user completes authorization, your backend receives a short-lived exchange code (ex_...) and a connection ID. Your server redeems the exchange code over an authenticated server-to-server call to retrieve connection metadata and tokens according to your app's token_exposure_policy.
Integration surfaces documented here:
| Surface | Who calls it | Auth | Purpose |
|---|---|---|---|
| Public connect/callback | End-user browsers | None (rate limited) | Start OAuth and receive IdP redirects |
| Server-to-server API | Your product backend | App API key or app ID + secret | Exchange codes, fetch/refresh/revoke tokens, manage connections |
| Webhook deliveries | Cliodot → your HTTPS endpoint | Signed payload | Real-time OAuth lifecycle events |
App, provider, and webhook configuration is done in the Cliodot portal — not via this API.
Provider attachments and connections carry an explicit protocol:
| Protocol | Connect flow | Token/session storage | Refresh |
|---|---|---|---|
oauth2 |
Authorization code + token exchange | access_token, optional refresh_token |
Supported when a refresh token exists |
oidc |
Same as OAuth2 + id_token handling |
OAuth tokens + id_token |
Same as OAuth2 |
saml |
SP-initiated SAML SSO | name_id, session_index, SAML attributes |
Not supported |
Legacy records without protocol are treated as oauth2.
Callbacks by protocol:
| Protocol | Callback method | Path |
|---|---|---|
oauth2, oidc |
GET |
/oauth/callback/:appId/:provider |
saml |
POST |
/oauth/callback/:appId/:provider |
| Priority | Source | Behavior |
|---|---|---|
| 1 | Connect scope / scopes param |
Used as-is; connector defaults are not copied |
| 2 | Provider scopes on attachment |
Used when no connect-time scope is sent |
| 3 | Connector auth template | Fallback when neither of the above is set |
Scope policies (configured on the provider in the portal; applied when no connect-time scope is sent):
| Policy | Behavior |
|---|---|
connector_default |
Provider scopes if set, else connector defaults |
extended |
Merges connector defaults with provider-configured scopes |
custom |
Provider-configured scopes only |
For template-based providers, connect-time scopes must be a subset of the attachment's selected_scopes.
Connection Storage#
| Mode | Storage | Lifetime |
|---|---|---|
persistent (default) |
MongoDB | Until revoked or deleted |
ephemeral |
Redis | 180 seconds from callback |
Set on the app in the portal (connection_storage) or override at connect time (connection_storage=ephemeral).
Ephemeral connections return full tokens and OAuth URLs on POST /oauth/token/exchange regardless of token_exposure_policy.