Administer

Single sign-on

Authenticate dashboard members through your identity provider.

Single sign-on lets your team members log in to the Agent Handler dashboard through your identity provider - Okta, Azure AD, Google Workspace, or any OIDC-compliant IdP - instead of managing a separate Agent Handler password. It’s the prerequisite for SCIM provisioning and is usually the first thing your security team will ask for.

SSO covers dashboard access only. It doesn’t change how end users authenticate to Connectors (that’s still Link) and doesn’t change the MCP URL’s auth model.

Before you start

You need admin access to your IdP and a role with the Manage users permission in Agent Handler (both Admin and Security have it). Once you flip “require SSO” on, members who haven’t completed first-time SSO will be locked out - fully provision your team in the IdP first.

Setting up OIDC

The flow is the same for every OIDC-compliant IdP. The specific clicks differ.

  1. Open Settings → Single sign-on.

  2. Click Configure SSO. The dialog shows the callback URL to register with your IdP:

    https://ah-api.merge.dev/sso/oidc/callback/

    Copy it from the dialog rather than typing it. It points at the Agent Handler API host (ah-api.merge.dev), not the dashboard host (ah.merge.dev), and the trailing slash is part of the URL. Most IdPs require an exact match, so a missing slash or the wrong host fails the exchange.

  3. From your IdP, register a new OIDC web application. Set the callback URL above as the allowed redirect URI, and grant the openid, email, and profile scopes. Agent Handler requests exactly those three.

  4. Copy the Discovery URL, Client ID, and Client secret from your IdP. The discovery URL is the full .well-known/openid-configuration document, not the bare issuer, because Agent Handler reads the authorization, token, and JWKS endpoints from it.

  5. Paste all three into the dialog and click Save configuration.

  6. Turn on the Enable SSO toggle. A saved configuration is inactive until you do, and you cannot require SSO while it’s off.

Test the flow before requiring it. Open an incognito window, go to ah.merge.dev/login/sso, enter your work email. You should bounce through your IdP and back to the dashboard.

SSO logs in existing members, it doesn't create them

The email you enter has to already belong to an Agent Handler member. SSO authenticates people; it doesn’t provision them. Invite them from Settings or provision them with SCIM first.

Per-IdP setup

  1. Okta Admin Console → Applications → Create App Integration → OIDC - OpenID Connect → Web Application.
  2. Sign-in redirect URI: https://ah-api.merge.dev/sso/oidc/callback/.
  3. Assign the application to the Groups that should have dashboard access.
  4. From the application’s General tab, copy the Client ID and Client secret.
  5. Discovery URL: https://<your-org>.okta.com/.well-known/openid-configuration. If you scoped the app to a custom authorization server, use https://<your-org>.okta.com/oauth2/<AUTH_SERVER_ID>/.well-known/openid-configuration instead.
  6. Paste all three into Agent Handler.

Requiring SSO

Once SSO works for your account, you can require it across the org. Turn on Require SSO in Settings → Single sign-on. The toggle needs a saved configuration with Enable SSO already on, and while Require SSO is on you cannot delete the configuration. After it’s on:

  • Members can no longer log in with email and password. The password form returns the same “unable to log in” error it returns for a wrong password, so members won’t be told why.
  • Password reset stops working too. Requesting a reset email silently does nothing, and an already-issued reset link is rejected.
  • Members not in the IdP Groups assigned to the Agent Handler app cannot log in at all.

Invitations don’t change. An invited member still sets a password when accepting the invite, they just can’t use it to log in while SSO is required.

Switch this on once your team is fully provisioned in the IdP. The admin who toggles it can lock themselves out if their IdP account isn’t set up correctly - test in incognito first.

How SSO interacts with email/password

If you don’t require SSO, both auth methods work in parallel. Members can log in either way. This is useful during rollout - you can configure SSO without forcing migration.

After Require SSO is on, only the SSO path works. To hand password access back to a member, turn Require SSO off first.

What SSO doesn’t do

SSO authenticates the dashboard only. Provisioning users (and mapping IdP Groups to Agent Handler roles) is SCIM. End-user auth to Connectors is still Link or Magic Link. MCP URL auth is an Access Key for Building an agent, and OAuth-through-IdP for Agent Handler for Employees.

Next

Auto-provision and deprovision members from your IdP with SCIM provisioning.