Use this file to discover all available pages before exploring further.
The identity provider (IDP) is the external service that authenticates the app’s end users. When one is configured, Alter verifies the JWTs the IDP issues, resolves which user is making each call, and looks up that user’s grants automatically.One IDP per app. Skip this page for backend-only apps that never see end users.
OIDC sign-in (optional) — adds a sign-in flow for app.authenticate() and the Wallet.
Webhook deprovisioning (optional) — real-time revocation when the IDP deletes a user.
Claim mappings (user-ID claim, group claim, role claim) lock after the first user signs in. Configure non-default claims before testing the first sign-in.
Pick the API or application whose JWTs Alter should accept.
Note the Issuer URL (https://<tenant>.us.auth0.com/ or the custom-domain URL) and Audience.
In the Alter portal → app’s Identity page:
Add Identity Provider → paste the issuer URL → Discover. Auth0 is recognized; claim mappings pre-fill.
Paste the audience.
For group-based authorization: add an Auth0 Action emitting a https://alter.dev/groups (or any namespaced) claim on the access token. Map it in the portal before the first sign-in.
Required only for app.authenticate() or the Wallet sign-in flow.In Auth0: Applications → Create Application → Regular Web Application. Paste both Alter redirect URIs into Allowed Callback URLs (comma-separated). Paste the Wallet logout URL (bare URL, no query params) into Allowed Logout URLs. Copy Client ID and Client Secret.In Alter: User Authentication (OIDC) section → paste credentials → Save.
In the Clerk Dashboard: note the instance URL (https://<app>.clerk.accounts.dev for dev, https://clerk.<custom-domain> for production). That’s the issuer.In the Alter portal → Identity → Add Identity Provider → paste the issuer → Discover. Clerk is recognized; claim mappings pre-fill (sub = Clerk user ID). For Clerk organizations with group-based authorization, set the group claim to org_memberships (or whatever the JWT template uses) before the first sign-in. Add Provider.
Requires a production Clerk instance. In Clerk: Configure → OAuth Applications → Create. Add both Alter redirect URIs. Copy Client ID and Client Secret. Paste into the Alter portal.
Clerk needs the webhook URL first. In Alter: note the Webhook URL; do not click Enable yet.In Clerk: Webhooks → Add Endpoint → paste the Alter URL. Subscribe to user.updated, user.deleted, organizationMembership.deleted. Copy the Signing Secret (whsec_...).Back in Alter: toggle Enable Webhooks → paste the secret → Save.
In the Okta Admin Console → Security → API → Authorization Servers → pick the server (default is default). Note the Issuer URI (https://<org>.okta.com/oauth2/default) and Audience.For group-based authorization: edit the authorization server → Claims → add a claim — name groups, include in Access Token, value type Groups, filter Matches regex.*.In the Alter portal → Identity → Add Identity Provider → paste the issuer URI → Discover. Okta is recognized. Paste the audience. Map the group claim before the first sign-in. Add Provider.
In Okta: Applications → Create App Integration → OIDC → Web Application. Sign-in redirect URIs = both Alter redirect URIs. Sign-out redirect URIs = the Wallet logout URL. Assign to the groups whose users should be able to sign into Alter Wallet. Copy Client ID and Client Secret. Paste into the Alter portal.
In Alter: Webhooks → Enable → copy the signing secret and endpoint.In Okta: Workflow → Event Hooks → Create Event Hook. URL = the Alter endpoint. Authentication field = Authorization, secret = the signing secret. Subscribe to user.lifecycle.delete.initiated, user.lifecycle.deactivate, user.lifecycle.suspend. Verify and Activate.
Custom Authorization Server — issuer URI is https://<org>.okta.com/oauth2/<server-id>, not the org URL.
Missing group claim — Okta emits no groups by default. Without the claim, group-bound grants don’t work.
Audience mismatch — default is api://default; JWTs with a different audience fail verification.
For any OIDC-compliant provider not listed above (OneLogin, Ping, Stytch, JumpCloud, etc.). Providers in the brokered-only row of the support table — Keycloak, Microsoft Entra ID, Amazon Cognito, Firebase Auth, Supabase Auth — are rejected at validation time by Custom OIDC and must instead be brokered through Auth0, Clerk, or Okta using the broker’s enterprise-connection feature.
JWKS URL (usually <issuer>/.well-known/jwks.json per OIDC discovery).
Audience (the value of the aud claim).
User-ID claim (default sub).
Group claim (provider-specific — common values: groups, cognito:groups, roles).
In the Alter portal → Identity → Add Identity Provider → paste the issuer URL → Discover. When OIDC discovery is exposed at <issuer>/.well-known/openid-configuration, Alter pulls JWKS automatically. Override claim mappings when the JWT uses non-standard names. Set group / role claims before any user signs in — they lock after first authentication.
Create an OIDC application (often called “Web App” or “Confidential Client”) at the provider. Add both Alter redirect URIs as callbacks. When the provider supports post_logout_redirect_uri, add the Wallet logout URL. Paste Client ID and Client Secret into the Alter portal.
In Alter: Webhooks → Enable → copy the secret and endpoint. In the IDP, configure a webhook subscribing to user-deleted / user-disabled events with the secret as an Authorization header.When the IDP supports no webhooks, deprovisioning waits until the deleted user’s JWT expires.
Brokered-only providers fail at save time. Issuer URLs from Keycloak, Entra, Cognito, Firebase, or Supabase are rejected. Use the broker pattern instead (Auth0 / Clerk / Okta with an enterprise connection).
Audience formatting — some providers send a string, some an array. Alter handles both; the portal value must match an entry.
