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 Auth0 Dashboard:
  1. Pick the API or application whose JWTs Alter should accept. Note the Issuer URL (typically https://<tenant>.us.auth0.com/) and Audience.
  2. For tenants using a custom Auth0 domain, use the custom-domain URL — that’s the issuer Auth0 stamps into JWTs.
In the Alter developer portal → app’s Identity page:
  1. Click Add Identity Provider.
  2. Paste the issuer URL, click Discover. Alter recognizes Auth0 and pre-fills the claim mappings.
  3. Paste the audience.
  4. For group-based authorization, configure a group claim. Auth0 does not emit groups by default — add an Auth0 Action to set https://alter.dev/groups (or any namespaced claim) on the access token, then map that claim in the portal 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. In Auth0:
  1. Applications → Applications → Create Application → Regular Web Application (not SPA — the callback hits the Alter backend).
  2. In Settings, paste both redirect URIs from the Alter portal into Allowed Callback URLs (comma-separated).
  3. Paste the Wallet logout URL shown in the portal into Allowed Logout URLs.
    Use the bare URL with no query parameters. Auth0 exact-matches this field. Example: if the Wallet callback is https://wallet.alterauth.com/api/auth/callback, the logout URL is https://wallet.alterauth.com/sign-in. Alter sends the appId through the OIDC state parameter — Auth0 echoes it back automatically.
  4. Copy Client ID and Client Secret from the same Settings page.
In the Alter portal:
  1. Open the User Authentication (OIDC) section on the app’s Identity page.
  2. Paste Client ID and Client Secret.
  3. Click Save Credentials.

​
3. Webhook deprovisioning (optional)

Pushes user-lifecycle events from Auth0 to Alter so deletions revoke grants in real time. In the Alter portal → Identity page → Webhooks section:
  1. Click Enable Webhooks.
  2. Copy the generated signing secret (shown once) and the webhook endpoint URL.
In Auth0:
  1. Monitoring → Streams → Create Stream → Custom Webhook.
  2. Payload URL = the Alter webhook endpoint.
  3. Authorization Token = the signing secret.
  4. Filter events to:
    • sdu — user deleted by admin
    • ublkdu — user blocked by admin
    • ubuu — user unblocked by admin
  5. Save.
Alter ignores sul (login) and limit_sul (rate limit) — those are not lifecycle events.

​
Test

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

​
Common pitfalls

  • Issuer URL trailing slash. Match exactly what Auth0 puts in the JWT iss claim. Auth0 typically includes the trailing /.
  • Custom domain mismatch. When JWTs use the custom domain but the portal has the tenant URL (or vice versa), verification fails. Check Auth0 → Settings → Custom Domains.
  • Missing group claim. Auth0 does not emit groups by default. Without an Action, group-based managed-secret access does not work.

​
See also