For AI agents: the complete documentation index is at https://docs.routebase.dev/llms.txt. Every page is also available as Markdown by appending index.md to its URL or by sending Accept: text/markdown.
Team & Settings

Single Sign-On (SSO)

With Single Sign-On, members of your organization sign in to Routebase through your company's identity provider instead of individual passwords. Routebase supports SAML 2.0, which works with Okta, Microsoft Entra ID, Google Workspace, OneLogin, Ping and any other SAML-compatible identity provider. It also supports SCIM 2.0 for automatic user provisioning. SAML connections and SCIM live on Settings → Single Sign-On, in the Security group of the settings sidebar. The page describes itself as "Configure SAML connections, manage SSO enforcement, and provision users via SCIM." The verified domains that enforcement is based on sit on their own page, Settings → Domains, right above it.

SAML SSO and SCIM provisioning are available on the Enterprise plan. On lower plans the sidebar entry shows a lock icon and the page shows an upgrade card. Opening the page also requires the org:manage-security permission, which Admins and Owners have.

Setup at a glance

  1. Verify your email domain by proving you own acme.com with a DNS TXT record on Settings → Domains. That page needs no Enterprise plan, and Custom Domains describes it.
  2. Create an SSO connection by walking through the connection wizard and exchanging SAML metadata with your identity provider.
  3. Test and activate the connection by running a test sign-in, then flipping it to Active.
  4. Optionally enforce SSO to require it for everyone whose email is on a verified domain.
  5. Optionally add SCIM so your identity provider can create, update and deactivate Routebase users automatically.

Step-by-step guides for your provider

Each guide covers the whole round trip. That means creating the SAML app in the identity provider, running the Routebase wizard, pasting the Entity ID and ACS URL back, and the optional SCIM and group-mapping steps:

For a different SAML 2.0 provider, start from SSO Setup Overview and choose the Generic SAML vendor preset.

You can have one active connection at a time. While a connection is active, the Create connection button is hidden, so disable the active one first if you need to set up a replacement.

Creating a connection

Click Create connection in the SSO Connections card. The Configure Single Sign-On wizard walks you through six steps:

Step What you do
Protocol Choose SAML 2.0. OIDC is shown but not yet available ("coming soon").
Vendor Pick Okta, Microsoft Entra ID, Google Workspace or Generic SAML. Each preset pre-fills the attribute mapping for that vendor.
Metadata Name the connection and paste your identity provider's metadata, either as a URL or as XML.
Mapping Map SAML assertion attributes to Routebase user fields.
Test Copy the Entity ID and ACS URL into your IdP, then run a test sign-in.
Activate Turn the connection on for your users.

Metadata

On the Metadata step, enter:

  • Connection name is required and only visible to admins. Use a name that identifies the provider and environment, such as Acme Okta Production.
  • IdP metadata URL is the preferred option, because Routebase auto-refreshes it when your identity provider rotates its signing certificates.
  • IdP metadata XML takes the full XML up to 1 MB, and you use it when your provider does not expose a public metadata URL. Google Workspace, for example, only offers a download.

The step includes vendor-specific guidance on where to create the SAML app in your identity provider and where to find its metadata, with a collapsible Show step-by-step checklist.

The metadata exchange goes both ways. After this step, the wizard shows the Entity ID and ACS URL that you paste back into your provider's SAML app configuration.

Attribute mapping

Map each Routebase user field to the claim name your identity provider sends:

Field Required Notes
Email Yes Unique identifier. SSO login fails without it.
First name and Last name No Used for the profile display name.
Avatar URL No Optional profile picture URL from the IdP.
Groups claim No A comma-separated list or a JSON array, used for Group to Role mapping.

Vendor presets fill these in for you. Two Microsoft Entra pitfalls are flagged inline in the editor:

  • Map email to user.userprincipalname rather than user.mail, because users without a mailbox have no mail value and would fail to sign in.
  • For groups, configure the group claim to emit "Cloud-only group display names". By default, Entra sends group object IDs as GUIDs, which do not match name-based group mappings.

Test and activate

Moving past the Mapping step saves the connection in Draft status. The Test step then shows the connection's Entity ID, ACS URL and Connection ID with copy buttons, so make sure these are configured in your identity provider. An Open test login button opens a test sign-in in a new tab, and completing that sign-in confirms the SAML handshake works end to end.

Finally, click Activate. Members of your organization can now sign in via your identity provider, and existing users are prompted to link their accounts on their next login.

Managing connections

Each connection in the SSO Connections card shows its name, a status badge, its connection ID, when it was last used, and the last error message if something went wrong. The badge reads Active, Draft, Disabled or Error. Four actions are available per connection:

  • Manage opens a details dialog. It carries the read-only identity provider details, which are Entity ID, ACS URL, Connection ID and Metadata URL, all with copy buttons. The editable fields are name, metadata URL, metadata XML, signing certificate, attribute mapping, and the Just-in-time provisioning toggle described as "Automatically create a Routebase user on first SSO login". Metadata XML and the signing certificate are stored encrypted and never displayed, so leave those fields blank to keep the current values.
  • Test opens a test sign-in in a new tab, the same as in the wizard.
  • Disable and Enable temporarily turn the connection off without deleting it.
  • Delete removes the connection after confirmation. Users can then no longer sign in with it, and this cannot be undone.

Enforcing SSO

SSO enforcement is per verified domain. Once a domain is verified, an SSO required switch appears next to it in the Verified domains card on Settings → Domains. Turning it on requires everyone whose email address is on that domain to sign in via SSO.

Existing members who currently use a password get a 14-day grace period. During it, a banner at the top of the app reads "Single Sign-On will be required soon. Password login for your account will be disabled in N days." and carries a Link account button to connect their SSO identity. After the grace period, or when an enforced user tries to sign in with a password, they see a "Single Sign-On required" page with a Continue to sign in button that routes them through SSO.

If Just-in-time provisioning is enabled on the connection, users on a verified domain get a Routebase account automatically on their first SSO sign-in, so no invitation is needed. If it is disabled, only users who already have a membership can sign in, whether they were invited or SCIM-provisioned.

Group role mappings

The Group Role Mappings card maps identity provider groups such as routebase-admins to Routebase custom roles, so role assignment follows your directory. Click Add mapping and fill in:

Field Purpose
External group name Must match the group name your identity provider sends in the groups claim, and matching is case-insensitive.
External group ID (optional) A stable provider-side identifier that survives group renames.
Routebase role The custom role members of this group receive.
Team (optional) Also add matched users to a team.
Priority Higher number wins when a user is in multiple mapped groups.

Users who match no mapping fall back to the SSO connection's default role. Deleting a mapping does not change anyone immediately, because existing members keep their current role until their next SSO login or SCIM update.

SCIM provisioning

SCIM 2.0 lets your identity provider create, update and deactivate Routebase users automatically, and it syncs groups as well. Your organization's SCIM endpoint is:

https://api.routebase.dev/scim/v2/{your-org-slug}

Calls are authenticated with bearer tokens from the SCIM Provisioning Tokens card:

  1. Click New token, give it a name that identifies the provider such as Okta Production, and optionally set an expiry date. Leaving it blank gives you a non-expiring token that you rotate manually.
  2. The full token is shown only once, in a copy dialog. Paste it straight into your provider's SCIM configuration, where it is sent as Authorization: Bearer .... After you close the dialog, only the token prefix remains visible.
  3. Use Rotate to invalidate a token and get a fresh one, shown once as at creation, or Revoke to kill it permanently. Provisioning calls signed with a revoked token fail immediately.

Each token row shows its prefix, when it was last used or "Never used", its expiry, and Revoked or Expired badges where applicable. Treat SCIM tokens like passwords, because anyone holding one can provision and deprovision users in your organization.

SSO and SCIM are independent, so you can run SSO with just-in-time provisioning and no SCIM, or both together.

Troubleshooting

  • Users cannot sign in. Check the connection's status badge, which must read Active, and the row's last error message, then run Test to reproduce the handshake yourself.
  • Sign-ins suddenly fail after working fine. Your identity provider may have rotated its signing certificate. Connections configured with a metadata URL refresh automatically, and if you pasted metadata XML, open Manage and paste the updated XML.
  • Some Microsoft Entra users fail while others work. Usually the email claim is mapped to user.mail and the failing users have no mailbox. Map it to user.userprincipalname instead.
  • Group mappings do not apply. Verify that your identity provider sends group names rather than object IDs in the groups claim, and that the mapping's external group name matches exactly. Matching itself is case-insensitive.
  • A user sees "Single Sign-On required". Their email domain has SSO enforcement turned on and they tried a password login, so this is enforcement working as designed.
  • New users cannot get in at all. If just-in-time provisioning is off, users need an existing membership before SSO sign-in succeeds, which means either an invitation or a SCIM-provisioned account.

The Audit Log records sign-in and membership events, which helps pin down when a failure started.

For a symptom-by-symptom walkthrough, see SSO Troubleshooting. It covers the SCIM error codes, a curl recipe to reproduce a provisioning failure, and why group mappings silently fall back to the default role.