OAuth Apps SDK

For Node.js and TypeScript projects, the cliodot npm package (v1.2.6+) provides OAuthAppClient — a typed wrapper around the public and server-to-server HTTP endpoints documented above.

OAuthAppClient is for developer integration only. It does not manage OAuth Apps, provider templates, portal connections, or webhooks. Configure those in the Cliodot portal.

HTTP integration remains fully supported and is the canonical API contract.

Install#

npm install cliodot

Client setup#

import { OAuthAppClient } from "cliodot";

const client = new OAuthAppClient({
  baseUrl: "https://api.cliodot.com",
  appId: "oauth_app_507f1f77bcf86cd799439011",
  appApiKey: "YOUR_APP_API_KEY",
  // appSecret: "a1b2c3d4...",  // alternative to appApiKey
  // debug: false,
});

One of appApiKey or appSecret is required for exchange and connections.*. Connect methods (connect.start, connect.poll, connect.buildUrl) do not send credentials.

Method overview#

client.connect.start(input)#

Starts an OAuth connect flow programmatically. Maps to POST /oauth/apps/:appId/connect. No authentication headers are sent.

Input (OAuthConnectStartInput)

Returns (OAuthConnectStartResponse)

Example — authorization code

const start = await client.connect.start({
  provider: "google",
  redirect_uri: "https://friendsconnect.com/auth/callback",
  scopes: ["openid", "email", "profile"],
  state: "csrf-token-from-your-app",
  external_user_id: "user_12345",
});
window.location.href = start.authorization_url!;

Example — client credentials (immediate)

import { isImmediateConnectResponse } from "cliodot";

const immediate = await client.connect.start({
  provider: "m2m",
  redirect_uri: "https://friendsconnect.com/auth/callback",
});
if (isImmediateConnectResponse(immediate)) {
  const exchanged = await client.exchange({
    code: immediate.exchange_code!,
    connection_id: immediate.connection_id!,
  });
}

Example — JWT bearer

await client.connect.start({
  provider: "m2m-api",
  redirect_uri: "https://friendsconnect.com/auth/callback",
  assertion: "eyJhbGciOiJSUzI1NiIs...",
});

client.connect.poll(input)#

Polls device authorization until complete. Maps to POST /oauth/apps/:appId/connect/poll. Retries automatically on 428 / authorization_pending using the interval below.

Input (OAuthConnectPollInput)

Returns (OAuthConnectPollResponse)

Example

import { isDeviceConnectResponse } from "cliodot";

const device = await client.connect.start({
  provider: "cli-tv",
  redirect_uri: "https://friendsconnect.com/auth/callback",
});
if (isDeviceConnectResponse(device)) {
  const done = await client.connect.poll({
    provider: "cli-tv",
    poll_state: device.poll_state!,
    pollIntervalMs: (device.poll_interval ?? 5) * 1000,
  });
  await client.exchange({
    code: done.exchange_code!,
    connection_id: done.connection_id!,
  });
}

client.connect.buildUrl(input)#

Builds a browser redirect URL for GET /oauth/apps/:appId/connect. Accepts the same fields as connect.start except grant-specific body fields (assertion, subject_token, etc.) — those require connect.start (POST).

const url = client.connect.buildUrl({
  provider: "google",
  redirect_uri: "https://friendsconnect.com/auth/callback",
  scopes: ["openid", "email", "profile"],
  state: "csrf-token",
});
window.location.href = url;

client.connect.isSamlPostBinding(response) / client.connect.buildSamlPostForm(response)#

Helpers for SAML POST binding after connect.start.

const saml = await client.connect.start({
  provider: "google-sso",
  redirect_uri: "https://friendsconnect.com/auth/callback",
});
if (client.connect.isSamlPostBinding(saml)) {
  const form = client.connect.buildSamlPostForm(saml)!;
}

client.exchange(input)#

Redeems an exchange code server-side. Maps to POST /oauth/token/exchange. Requires S2S credentials.

Input (OAuthExchangeInput)

Returns (OAuthExchangeResponse)

const result = await client.exchange({
  code: "ex_a1b2c3d4e5f6789012345678901234567890ab",
  connection_id: "conn_507f1f77bcf86cd799439014",
});

client.connections.get(connectionId)#

Returns sanitized connection metadata. Maps to GET /oauth/connections/:connectionId.

Returns: { ok: true, connection: OAuthSanitizedConnection }

const { connection } = await client.connections.get("conn_507f1f77bcf86cd799439014");

client.connections.getToken(connectionId) / client.connections.sync(connectionId)#

Fetches access token (and related fields per policy). Maps to GET /oauth/connections/:connectionId/token. sync is an alias for getToken.

Returns (OAuthTokenResponse)

const token = await client.connections.getToken("conn_507f1f77bcf86cd799439014");
const synced = await client.connections.sync("conn_507f1f77bcf86cd799439014");

client.connections.refresh(connectionId)#

Refreshes tokens using the stored refresh token. Maps to POST /oauth/connections/:connectionId/refresh.

Returns (OAuthConnectionWithTokenResponse): connection plus refreshed token fields.

const refreshed = await client.connections.refresh("conn_507f1f77bcf86cd799439014");

client.connections.revoke(connectionId, input?)#

Revokes a connection at the provider when supported. Maps to POST /oauth/connections/:connectionId/revoke.

Returns: { ok: true, revoked: true }

await client.connections.revoke("conn_507f1f77bcf86cd799439014", {
  reason: "user_logged_out",
});

client.connections.delete(connectionId)#

Deletes the connection record. Maps to DELETE /oauth/connections/:connectionId.

Returns: { ok: true, deleted: true }

await client.connections.delete("conn_507f1f77bcf86cd799439014");

Response type guards and utilities#

Import from cliodot alongside OAuthAppClient:

import {
  OAuthAppClient,
  isImmediateConnectResponse,
  isDeviceConnectResponse,
  pollDeviceConnectWithBackoff,
} from "cliodot";

Error handling#

SDK methods throw CliodotApiError on failure with message, status, and code (when the API returns one).

import { CliodotApiError } from "cliodot";

try {
  await client.exchange({ code: "ex_bad", connection_id: "conn_1" });
} catch (err) {
  if (err instanceof CliodotApiError) {
    console.error(err.code);
  }
}

Common codes: OAUTH_EXCHANGE_CODE_INVALID, OAUTH_UNAUTHORIZED_APP, OAUTH_CONNECTION_REVOKED, OAUTH_CONNECTION_EXPIRED, OAUTH_PROVIDER_ERROR.