Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.alterauth.com/llms.txt

Use this file to discover all available pages before exploring further.

This page is the per-provider supplement to the IDP overview. Read that first.

​
1. JWT verification

In the Clerk Dashboard:
  1. Note the instance URL: https://<app>.clerk.accounts.dev (development) or https://clerk.<custom-domain> (production with a custom domain). This is the issuer.
  2. Decide which JWT template to send to Alter. Clerk’s session token works out of the box.
In the Alter developer portal → app’s Identity page:
  1. Click Add Identity Provider.
  2. Paste the issuer URL, click Discover. Alter recognizes Clerk and pre-fills the claim mappings.
  3. The default sub claim is Clerk’s user ID; that’s what Alter keys user records on.
  4. For Clerk organizations with group-based authorization, set the group claim to org_memberships (or whatever the JWT template uses) before any user signs in.
  5. Click Add Provider.

​
2. OIDC sign-in (optional)

Required only for vault.authenticate() or the Wallet sign-in flow. Requires a production Clerk instance. In the Clerk Dashboard:
  1. Configure → OAuth Applications → Create OAuth Application.
  2. Add both redirect URIs from the Alter portal as allowed callbacks.
  3. Copy Client ID and Client Secret.
In the Alter portal:
  1. Open the User Authentication (OIDC) section.
  2. Paste credentials and Save.

​
3. Webhook deprovisioning (optional)

Clerk’s flow is reversed from Auth0: create the endpoint in Clerk first, then paste its signing secret into Alter. In the Alter portal → Identity page → Webhooks section:
  1. Note the Webhook URL shown for the app. Do not click Enable yet — Clerk needs the URL first.
In the Clerk Dashboard:
  1. Webhooks → Add Endpoint → paste the Alter webhook URL.
  2. Subscribe to:
    • user.updated
    • user.deleted
    • organizationMembership.deleted
  3. Copy the displayed Signing Secret (whsec_...).
Back in the Alter portal:
  1. Toggle Enable Webhooks and paste the signing secret.
  2. Click Save Secret.
To rotate later: generate a new signing secret in Clerk’s endpoint settings, then click Rotate Secret in the Alter portal and paste the new value.

​
Test

  1. Sign in as a test user through Clerk → confirm the user appears in the Alter portal.
  2. Delete the test user in Clerk → confirm their grants are revoked in Alter.

​
Common pitfalls

  • Development vs production instance. OIDC sign-in requires production. JWT verification works in either, but issuer URLs differ.
  • Custom JWT template. With a non-default JWT template, ensure the sub claim still carries the user ID Alter should key on. Override the user-ID claim mapping in the portal if needed (only before first sign-in).

​
See also