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.

​
Prerequisites

Before starting, make sure the following are in place:
  • An Alter Vault account with an application created in the Developer Portal
  • An Auth0 tenant or Clerk application (or any OIDC-compliant identity provider)
  • The Python SDK or TypeScript SDK installed

​
Setup Steps

1
Add the Identity Provider
2
In the Developer Portal, navigate to the application’s Identity page.
3
  • Click Add Identity Provider
  • Enter the OIDC issuer URL (e.g., https://your-tenant.us.auth0.com or https://your-app.clerk.accounts.dev)
  • Click Discover to auto-detect the IDP type, user ID claim, and group claim
  • Review the suggested claim mappings and override if needed
  • Click Add Provider
    • 4
    One IDP per app at a time. Each application can have only one active identity provider configuration. To switch providers, remove the existing IDP configuration and then add the replacement.
    5
    Auto-detection: Alter Vault recognizes Auth0 and Clerk from the issuer URL and automatically configures the correct claim mappings. Any other OIDC-compliant provider defaults to custom_oidc and uses the standard sub claim.
    6
    Claim mappings lock after first user sign-in. The user ID claim, group claim, and role claim cannot be changed once the first user authenticates through the identity provider. If the IDP does not include group or role claims by default (e.g., Auth0 requires a custom Action), leave these fields empty and set them before any user signs in.
    7
    Pass JWT When Retrieving Tokens
    8
    When the application makes API calls through Alter Vault, include the end user’s JWT issued by the identity provider. This lets Alter Vault identify the user and enforce access policies.
    9
    Python SDK
    from alter_sdk import AlterVault, HttpMethod

vault = AlterVault(
    api_key="alter_key_...",
    caller="my-agent",
    user_token_getter=lambda: get_user_jwt(),  # Returns JWT from the identity provider
)

# JWT is automatically included by the SDK via user_token_getter
response = await vault.request(
    HttpMethod.GET,
    "https://api.example.com/data",
    provider="google",
)
    TypeScript SDK
    import { AlterVault, HttpMethod } from "@alter-ai/alter-sdk";

const vault = new AlterVault({
  apiKey: "alter_key_...",
  caller: "my-agent",
  userTokenGetter: () => getUserJwt(), // Returns JWT from the identity provider
});

// JWT is automatically included by the SDK via userTokenGetter
const response = await vault.request(
  HttpMethod.GET,
  "https://api.example.com/data",
  { provider: "google" },
);
    10
    Automatic sync: The first time Alter Vault sees a JWT for a new user, it automatically creates a user record and syncs group memberships from the JWT claims. Subsequent requests update the user’s profile.
    11
    Enable User Authentication (OIDC)
    12
    To let end users sign in through the IDP --- for vault.authenticate() in the SDK or the Wallet dashboard --- configure OIDC client credentials.
    13
  • In the Developer Portal → the app’s Identity page, expand the User Authentication (OIDC) section
  • Step 1 --- Register redirect URIs: Copy both redirect URIs (SDK callback and Wallet callback) and add them as allowed redirect/callback URIs in the OAuth application on the IDP
  • Step 2 --- Enter credentials: Copy the Client ID and Client Secret from the IDP’s OAuth application and paste them into the Developer Portal, then click Save Credentials
    • 14
    What this enables: Once configured, the SDK’s vault.authenticate() method opens a browser-based login flow through the IDP, and the Wallet dashboard gains a sign-in page for end users. User accounts are created automatically on first authentication.
    15
    Per-Provider Setup
    16
    Auth0
    1. Go to Auth0 Dashboard → Applications → Applications and click Create Application
    2. Choose Regular Web Application (not SPA --- the callback goes to the Alter Vault backend)
    3. In the app’s Settings tab, paste both redirect URIs into Allowed Callback URLs (comma-separated)
    4. In the same Settings tab, paste the Wallet logout URL shown in the Developer Portal into Allowed Logout URLs.
      Use the bare URL with no query parameters. Auth0 exact-matches this field, so https://wallet.alterauth.com/sign-in works but https://wallet.alterauth.com/sign-in?appId=… will be rejected. Alter Vault sends the appId through the OIDC state parameter, which Auth0 echoes back automatically --- no per-app URL is needed.Example: if the Wallet callback shown in the Developer Portal is https://wallet.alterauth.com/api/auth/callback, the logout URL is https://wallet.alterauth.com/sign-in.
      Without this step the Wallet’s “Sign out” button cannot return users to the sign-in page after Auth0 clears its session, and end users cannot switch accounts.
    5. Copy the Client ID and Client Secret from the same Settings page into the Developer Portal
    If using a custom Auth0 domain (e.g., auth.yourcompany.com), the issuer URL registered in Alter Vault must match the issuer in the JWTs Auth0 issues. Check Auth0 Dashboard → Settings → Custom Domains.
    Clerk
    1. In the Clerk Dashboard, go to Configure → OAuth Applications (requires a production instance)
    2. Create a new OAuth application and add both redirect URIs from the Developer Portal as allowed callbacks
    3. Copy the Client ID and Client Secret into the Developer Portal
    Clerk’s JWT issuer URL follows the pattern https://your-app.clerk.accounts.dev for development instances or https://clerk.your-domain.com for production instances with a custom domain.
    17
    Python SDK
    from alter_sdk import AlterVault

vault = AlterVault(
    api_key="alter_key_...",
    caller="my-agent",
)

# Opens a browser window for the user to sign in via the IDP
auth_result = await vault.authenticate()
print(auth_result.user_info)  # User profile from the IDP
    TypeScript SDK
    import { AlterVault } from "@alter-ai/alter-sdk";

const vault = new AlterVault({
  apiKey: "alter_key_...",
  caller: "my-agent",
});

// Opens a browser window for the user to sign in via the IDP
const authResult = await vault.authenticate();
console.log(authResult.userInfo); // User profile from the IDP
    18
    Enable Webhooks for Deprovisioning
    19
    For real-time user lifecycle sync, enable webhooks so the identity provider pushes user.deleted and user.suspended events to Alter Vault. The setup differs by provider because Clerk (via Svix) generates its own signing secret, while Auth0 accepts any shared token.
    20
    Auth0
    1. In Developer Portal → the app’s Identity page → Webhooks section, click Enable Webhooks. Copy the generated signing secret (shown only once) and the webhook endpoint URL.
    2. In Auth0 Dashboard → Monitoring → Streams, create a new Custom Webhook log stream.
    3. Paste the webhook endpoint URL as the Payload URL.
    4. Paste the signing secret into the Authorization Token field.
    5. Filter the stream to sdu (user deleted by admin), ublkdu (user blocked by admin), and ubuu (user unblocked by admin) events. These are the three admin-initiated lifecycle events Alter Vault acts on; login events (sul) and rate-limit events (limit_sul) are intentionally ignored because they are not per-user lifecycle changes.
    6. Save the log stream.
    Clerk
    Clerk generates the signing secret inside the Clerk Dashboard, so the flow is reversed: create the endpoint in Clerk first, then paste its signing secret into the Developer Portal.
    1. In Developer Portal → the app’s Identity page → Webhooks section, note the Webhook URL shown for the app.
    2. In Clerk Dashboard → Webhooks, click Add Endpoint and paste the webhook URL as the endpoint URL.
    3. Subscribe to user.updated, user.deleted, and organizationMembership.deleted events.
    4. Clerk displays a Signing Secret for the endpoint (starts with whsec_). Copy it.
    5. Back in the Developer Portal, toggle Enable Webhooks and paste the signing secret into the dialog, then Save Secret.
    To rotate later: generate a new signing secret in Clerk’s endpoint settings, then use Rotate Secret in the Developer Portal and paste the new value.
    21
    Auth0 only — save the generated signing secret immediately. The Developer Portal displays it once when webhooks are enabled. If lost, use Rotate Secret to generate a new one (the old one is immediately invalidated). Clerk signing secrets live in the Clerk Dashboard; re-copy them from there if needed.
    22
    Test Deprovisioning
    23
    To verify the integration works end-to-end:
    24
  • Sign in as a test user through the identity provider (this creates the user in Alter Vault via JWT lazy sync)
  • Delete the test user in the identity provider
  • Verify their OAuth grants are revoked in Alter Vault

    • ​
    What Happens Behind the Scenes

    When the application passes a JWT or the identity provider sends a webhook event:
    1. User identity is resolved — Alter Vault maps the JWT sub claim to an internal user record
    2. Groups are synced — Group memberships from JWT claims are synced to Alter Vault
    3. Connections are linked — OAuth grants are associated with the user for lifecycle management
    4. Policies are evaluated — Group-based access policies can restrict which providers a user can access
    When a user is deprovisioned:
    1. User status is set to deprovisioned
    2. All linked OAuth grants are immediately revoked
    3. All stored tokens are permanently deleted
    4. Subsequent token requests for this user are denied

    ​
    Next Steps