Skip to main content

Set up Auth0 for evaluation

This path applies where corporate identity provider (IdP) admin access is unavailable, or where the corporate IdP is not preferred for a proof of concept. Complete every step below in order: this is the full Auth0 setup for Step 1 of the fast track. On completion, single sign-on (SSO) works and the Admin Console shows providers and models.

One linear path

Do not treat Auth0 setup and management plane onboarding as separate jobs. The onboarding wizard is opened mid-flow to copy the Redirect URI, then Auth0 is finished, the credentials are pasted back into the same wizard, and onboarding is completed.

warning

Only change the settings listed below. Leave everything else at its default.

What is in place when done​

ValueWhere it comes from
Issuerhttps://<DOMAIN>/ (trailing slash) from the Auth0 Domain
Discovery URLhttps://<DOMAIN>/.well-known/openid-configuration
Client IDAuth0 application Settings
Client SecretAuth0 application Settings

Also registered in Auth0: Allowed Callback URLs, Allowed Web Origins, and optionally Allowed Logout URLs.

Step 1: create an Auth0 tenant​

  1. Go to https://auth0.com and sign up (or sign in).
  2. Create a tenant if prompted (any region is fine for evaluation).
  3. Confirm that the Auth0 Dashboard opens and applications can be created.

Step 2: open management plane onboarding and copy the Redirect URI​

  1. Open the Admin Console URL and start Management plane onboarding.
  2. Complete organization details if prompted, then reach the Configure SSO (Corporate Login) step.
  3. Click IdP setup guide at the top of the form. A panel opens with the tenant Redirect URI.
  4. Use the copy icon. The URL looks like:
https://api.<tenant>.tetrate.ai/v1/auth/sso/callback/corporate
tip

Always copy the Redirect URI from the IdP setup guide panel. Do not type it from memory or paste the placeholder from this page: any mismatch causes redirect_uri_mismatch at sign-in.

Leave the wizard open on the Configure SSO step. Auth0 values are pasted into this form after Step 6.

Step 3: create the Auth0 application​

  1. In the Auth0 Dashboard, go to Applications.
  2. Click + Create Application.
  3. Select Create Manually.
  4. Enter a recognizable name, for example Tetrate Agent Router Enterprise.
  5. Leave the This application is owned by a third party toggle off. Select Regular Web Application (the dialog preselects Native).
  6. Click Create.
Do not enable third-party ownership

Leave the "This application is owned by a third party" toggle off. Third-party applications require PKCE, which this integration does not support; sign-in fails immediately with invalid_request: The PKCE protocol extension is required. This setting cannot be changed after creation; if set wrong, delete the app and create a new one.

Step 4: configure application settings​

  1. Open the Settings tab.
  2. Under Basic Information, copy Domain, Client ID, and Client Secret into a notes app. The Client Secret is also available on the Credentials tab.
  3. Under Application Properties, optionally set Application Logo to any logo URL (this only affects the branding shown to the team on the Auth0 login screen).
  4. Open the URLs tab. The Application URIs settings are no longer on the Settings tab.
  5. Under Redirect URLs, set Allowed Callback URLs to the Redirect URI copied in Step 2 (exact match).
  6. Still under Redirect URLs, optionally set Allowed Logout URLs to:
https://auth.<tenant>.tetrate.ai
  1. Under Cross-origin (CORS), set Allowed Web Origins to the tenant hostnames, listed as Allowed Origins on the Admin Console's Settings → SSO tab:
https://dashboard.<tenant>.tetrate.ai
https://auth.<tenant>.tetrate.ai
https://router.<tenant>.tetrate.ai
https://app.<tenant>.tetrate.ai
https://api.<tenant>.tetrate.ai

Replace <tenant> with the same tenant segment as in the Redirect URI (for example, if the callback host is api.acme.tetrate.ai, use acme).

  1. Click Save to store the URL changes.
note

The auth service is deprecated and is removed no earlier than 0.11. Nothing needs to change now. URLs on auth.<tenant>.tetrate.ai keep working.

Step 5: create an Auth0 user​

  1. In Auth0, go to User Management → Users → Create User → Create via UI.
  2. Leave Connection set to Username-Password-Authentication. Enter a reachable Email and a Password Auth0 allows, then click Create. This email must appear under Admin emails in the Tetrate SSO form.
  3. Check that the email's domain is on the deployment's allowed email domains. Agent Router refuses a sign-in from any other domain, even when Auth0 accepts it.
Admin emails is not optional in practice

If Admin emails is left empty or omits this user's email, the first SSO sign-in lands as a regular, non-admin user, and because there is no email/password fallback in Agent Router, nobody can grant admin access from inside the product. Recovering from this requires contacting Tetrate Support. Set this field before finishing Step 7.

Step 6: copy the Auth0 settings​

From the application Settings tab, build the values for the Tetrate SSO form:

FieldHow to build it
Issuerhttps://<Domain>/ with a trailing slash. Example: Domain acme.us.auth0.com → Issuer https://acme.us.auth0.com/
Discovery URL<Issuer>/.well-known/openid-configuration
Client IDFrom Basic Information
Client SecretFrom Basic Information
Scopesopenid, profile, email
Admin emailsThe Auth0 user email from Step 5 (plus any other admins)
Attribute mappingDefault email → email

Step 7: paste into the wizard and finish onboarding​

  1. Return to the Configure SSO step left open in Step 2.
  2. Fill in Issuer, Discovery URL (if required), Client ID, Client Secret, scopes, admin emails, and attribute mapping.
  3. Click Configure.
  4. Continue the wizard: connect at least one LLM provider and select models.
  5. Skip the data-plane credential step: Fully Managed only. Do not create, regenerate, or download a data-plane credential.
  6. Complete setup.

If the wizard is already closed without SSO, configure SSO from the Admin Console using Configure SSO Part 1, then confirm providers and models under Models / Providers.

Step 8: verify SSO sign-in​

  1. Sign out of the Admin Console if the session is still on initial admin credentials.
  2. Sign in with the Auth0 user from Step 5 (Sign in with SSO / corporate login).
  3. Confirm the Admin Console loads and shows the configured providers and models.
  4. Confirm the default project is ready: its default gateway's endpoint is set to the assigned proxy host (set it if empty), the admin user is a project User, and the project-scoped models to be called are enabled.

Verify (Step 1 complete)​

  • Auth0 Regular Web Application exists with callback and web origins from the live Redirect URI.
  • SSO sign-in with the Auth0 user succeeds.
  • Admin Console catalog shows providers and models, and the default project is ready for traffic.

Team prep: add teammates in Auth0​

The fast track's team step needs 2 to 5 people signed in through the same Auth0 tenant. Corporate IdP invites do not apply on this path.

  1. In Auth0, go to User Management → Users → Create User → Create via UI for each teammate (use emails they control). Each teammate's email domain must be on the deployment's allowed email domains; ask Tetrate Support to add any missing domain first.
  2. Share the Console URL (https://router.<tenant>.tetrate.ai) and tell them to Sign in with SSO (Auth0).
  3. After each teammate's first SSO login, their Agent Router user record appears in the Admin Console Users list.
  4. Signing in needs no team, project, or role. A teammate who signs in holds only the default user role, which does not grant Admin Console access, until a Super Admin grants them a role directly or through a team. Grant only what each teammate needs; see Manage roles and permissions.
  5. Continue with Step 6 of the fast track: teammates connect passthrough credentials, point their agents at the gateway, and get team budgets.

Where to go next​

Continue the fast track to route the first request. At the team step, return to Team prep.