Skip to navigation

Connect Rydhm

Give the teams that use your app a Connect Rydhm button instead of asking them for API keys.

If your app is used by other teams (a CRM, a dialer, a helpdesk), each of them has their own Rydhm workspace. With Connect Rydhm, an admin of that workspace clicks Connect Rydhm in your app, signs in to Rydhm, checks what your app may do and clicks Allow. Your server gets a key for their workspace, and the signing secret of a webhook Rydhm adds for your app. Nobody copies a key.

It’s OAuth 2.0 with the authorization code and PKCE (S256), so any standard OAuth library works too.

Clicks "Connect Rydhm" Redirect to Rydhm (client_id, redirect_uri, state, code_challenge) Signs in, picks the workspace, clicks Allow Redirect to your redirect_uri?code=…&state=… GET /callback?code=…&state=… POST /v1/oauth/token (code, code_verifier, client secret) { access_token, workspace, webhook_secret } Admin (browser) Your app's server Rydhm

1. Register your app

In the Rydhm app, Developers → Connect Rydhm → Register an app:

FieldWhat to put
NameWhat your customers see on the Connect screen, like AIX CRM.
Send people back toYour callback address, exactly as your app sends it (one per line). https:// only; http://localhost is allowed while you develop. Matching is exact: no trailing-slash or query leniency.
What it may doMake and read sales calls (calls:read + calls:write) is preselected. Choose picks any permission.
Send call updates toOptional. Rydhm adds a webhook endpoint for it in each workspace that connects, for the sales-call events (call.completed, call.summary.ready, …), and your app gets its signing secret with the key.

Rydhm shows the client id (rydhm_app_…) and the client secret (rydhm_cs_…). The secret is shown once: save both in your app’s settings (RYDHM_CLIENT_ID, RYDHM_CLIENT_SECRET, on the server). Lost it? Roll a new one; workspaces already connected keep working.

2. The Connect button

Make a PKCE pair and a state, keep both in the user’s session, and send them to the consent page.

connect.ts
import { oauth } from "@rydhm/sdk";
app.get("/api/rydhm/connect", requireAdmin, async (req, res) => {
const { codeVerifier, codeChallenge } = await oauth.pkce();
const state = crypto.randomUUID();
req.session.rydhm = { codeVerifier, state };
res.redirect(oauth.authorizeUrl({ clientId: process.env.RYDHM_CLIENT_ID!, redirectUri: REDIRECT_URI, state, codeChallenge }));
});

On Rydhm, the admin sees which workspace they’re connecting (they can switch), what your app may do in plain words, and where they’ll go back. Only a workspace admin can allow. Cancel sends them back with error=access_denied&state=…. An unknown client_id or an address you didn’t register shows an error on Rydhm and never redirects.

3. The callback

Check state, then swap the one-time code for the workspace’s key. A code works once, for 10 minutes.

callback.ts
import { oauth, Rydhm } from "@rydhm/sdk";
app.get("/api/rydhm/callback", requireAdmin, async (req, res) => {
const saved = req.session.rydhm;
if (!saved || req.query.state !== saved.state || !req.query.code) return res.redirect("/settings?rydhm=cancelled");
const t = await oauth.exchangeCode({
code: String(req.query.code),
redirectUri: REDIRECT_URI,
codeVerifier: saved.codeVerifier,
clientId: process.env.RYDHM_CLIENT_ID!,
clientSecret: process.env.RYDHM_CLIENT_SECRET,
});
await saveConnection({ key: t.accessToken, workspace: t.workspace, webhookSecret: t.webhookSecret }); // encrypted
res.redirect("/settings?rydhm=connected");
});

The client secret may also be sent as HTTP Basic (Authorization: Basic base64(client_id:client_secret)). Errors follow RFC 6749 (error, error_description):

StatuserrorWhen
400invalid_requestA field is missing.
401invalid_clientUnknown client_id, or a wrong or missing client secret.
400invalid_grantThe code is unknown, expired, already used, for another app; redirect_uri differs; code_verifier doesn’t match.
400unsupported_grant_typegrant_type isn’t authorization_code.
429rate_limitedMore than 30 a minute from one address, or 60 for one app.

Never retry an exchange with the same code: if a code is presented twice, the connection it made is revoked, in case it leaked. Start the connection again instead.

4. Use the key

access_token is an ordinary Rydhm API key for that workspace, with the permissions the admin allowed. Use it like any key, for example to start sales calls:

const rydhm = new Rydhm({ apiKey: connection.key });
const { workspace, salesCalls } = await rydhm.oauth.connection();
// "Connected to AIX Staging · calls go out from (628) 212-6768"
if (!salesCalls.ready) showSetupLink(salesCalls.setupUrl); // no number switched on for sales calls yet

GET /v1/oauth/connection takes only a key Connect Rydhm issued (403 not_a_connected_app otherwise).

The key doesn’t expire, even in a workspace that requires API keys to: an admin allowed it, and disconnecting ends it at once. In that workspace it shows in Developers → API keys, locked, as Managed by the AIX CRM connection.

Disconnecting

  • From your app: DELETE /v1/oauth/connection (rydhm.oauth.disconnect()). Then forget the key and the webhook secret.
  • From Rydhm: an admin clicks Disconnect in Settings → Connected apps. Your next request with the key gets 401: show Connect Rydhm again.

Either way the key stops working at once and the webhook endpoint Rydhm added is removed. Connecting the same app to the same workspace again replaces the old connection (with a new key and webhook secret). Every connect and disconnect is in the workspace’s audit log.

Webhooks

When your app has a Send call updates to address, each connection adds an endpoint for it in that workspace. Deliveries are Standard Webhooks, signed with the webhook_secret from the token exchange: verify them with verifyWebhook (@rydhm/sdk) or verify_webhook (rydhm). If the endpoint can’t be added (the workspace already has 10), the token answer has webhook_error and the connection still works.