Connect Rydhm
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.
1. Register your app
In the Rydhm app, Developers → Connect Rydhm → Register an app:
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.
TypeScript
Python
Any language
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.
TypeScript
Python
HTTP
The client secret may also be sent as HTTP Basic (Authorization: Basic base64(client_id:client_secret)). Errors follow RFC 6749 (error, error_description):
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:
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.