Clerk
Connect the Clerk instance used by your app, then pass its session token to Modem. Clerk’s session-token guide describes the issuer and authorized-party fields in those tokens.
Configure the connection
- Open Projects → your project → General → Authentication → Clerk.
- Supply the Clerk secret key for that instance, directly or through a linked 1Password field.
- Add every authorized frontend origin that should identify customers, including the protocol. Use your actual local development origin rather than a copied port number.
- Choose the customer-deprovisioning policy and connect. Use connection verification after changing credentials or frontend configuration.
The authorized-party list accepts 1–20 origins: HTTPS origins, HTTP origins on localhost, or Chrome extension origins, with no paths or query strings. Modem checks the token’s azp against that list and the token’s iss against the connected Clerk issuer. A token from a different Clerk instance is not accepted merely because it has a valid Clerk signature. Chrome extension origins must use their actual chrome-extension://… origin.
Supply a session token
For an initialized, signed-in Clerk frontend client:
import { createCustomerClient } from '@preternatural-js/client-sdk'
const client = createCustomerClient({
environment: 'production',
projectId: 'YOUR_PROJECT_ID',
authentication: {
type: 'identity-token-provider',
getIdentityToken: async () => {
const token = await clerk.session?.getToken()
if (!token) throw new Error('Sign in before using Modem')
return token
}
}
})Here clerk is your initialized Clerk instance. Use a current session token, not the secret key or an arbitrary JWT template with different fields. Modem expects a subject, issuer, issued-at time and authorized party in the verified session token. See Clerk’s Session object for getToken().
Configure lifecycle delivery
In the Clerk connection, open webhook setup. Register the endpoint and user.created, user.updated and user.deleted events shown by Modem. Save the endpoint’s webhook signing secret in Modem, directly or through 1Password. This is a different secret from the Clerk server API key.
Saving the signing secret leaves delivery awaiting verification. A correctly signed event from the matching Clerk instance verifies the connection; a saved form alone does not prove delivery. Use Clerk’s webhook dashboard to send a test and inspect delivery failures. Follow Clerk’s webhook setup guide when configuring the provider side.
A verified deletion event revokes that provider subject and suspends its Modem customer. If the selected policy also cancels linked subscriptions, cancellation can finish after webhook receipt. A successful webhook HTTP response does not prove every downstream cancellation has completed. Inspect the customer’s payment history and resolve failed cancellation separately before retrying destructive actions.
Common failures
| Symptom | Check |
|---|---|
| Missing authorized party | Add the frontend origin that issued this session token. |
| Issuer mismatch | Use the server key and session from the same Clerk instance. |
| Saved webhook is not verified | Check signing secret, registered events, endpoint reachability and instance. |
| Temporary key-fetch failure | Retry verification; do not interpret an upstream signing-key outage as user deletion. |
Disconnecting or replacing the connection can invalidate existing customer identities. Read provider lifecycle first.