Setting Up Single Sign-On (SSO)
Enterprise Single Sign-On (SSO) lets your users sign into merchi.ai using your existing corporate credentials. Once active:
- Users sign in through your company’s identity provider — no separate merchi.ai password required
- New users are automatically onboarded to your workspace on first login
- Their profile (name, job title, company) is populated from your directory
- Roles can be managed via your identity provider groups
To enable SSO for your organisation, contact merchi.ai support. The steps below walk your IT team through what they need to configure on your identity provider.
merchi.ai Service Provider Details
Your IT team will need these when creating the SAML application:
| Field | Value |
|---|---|
| SP Entity ID / Identifier | https://api.merchi.ai/auth/v1/sso/saml/metadata |
| ACS URL (Reply URL / Assertion Consumer Service URL) | https://api.merchi.ai/auth/v1/sso/saml/acs |
| Sign-on URL | https://app.merchi.ai/sign-in |
| Name ID format | Email address |
| Name ID value | User’s primary email address |
Required Attribute Mappings
Your identity provider needs to send the following attributes in the SAML assertion. Map your directory fields to the exact App attribute names shown:
| Your directory field | App attribute name |
|---|---|
| First name | first_name |
| Last name | last_name |
| Job title | job_title |
| Company / Organisation | company |
These populate the user’s merchi.ai profile automatically on each login.
Role Mapping via Groups (Optional but Recommended)
You can control whether users get Admin or Member access by creating groups in your identity provider and mapping them to a single attribute.
Step 1 — Create groups in your identity provider:
Create groups for each access level your users need. You can name them anything — just note the names as you’ll need to share them with us so we can configure the role mapping.
| Group purpose | Example name |
|---|---|
| merchi.ai Admins | merchi-admins |
| merchi.ai Members | merchi-members |
Add users to the appropriate group.
Step 2 — Add a Group membership attribute mapping in your SAML application:
| Source | App attribute name |
|---|---|
| Group membership (select the groups above) | merchi_groups |
merchi.ai will assign the corresponding role on each login. Users with no matching group receive Member access by default.
IdP-Specific Instructions
Google Workspace
- Sign in to Google Admin Console
- Apps → Web and mobile apps → Add app → Add custom SAML app
- Name the app (e.g. “merchi.ai”) and click Continue
- Download the IdP metadata (send this to merchi.ai) and click Continue
- Enter the Service Provider details from the table above
- Set Name ID format to EMAIL and Name ID to Basic Information > Primary email
- Click Continue, then add the attribute mappings:
- Basic Information > First name →
first_name - Basic Information > Last name →
last_name - Employee Details > Title →
job_title - Organization →
company
- Basic Information > First name →
- Under Group membership, add your merchi.ai role groups →
merchi_groups - Save the app and turn it On for the relevant users or org units
Important notes:
- Users must be members of a group (not just owners) for the group to appear in the assertion
- If a user belongs to multiple merchi.ai groups, only one will be sent — put the highest-privilege group first in the list order
Azure AD
- Sign in to the Azure Portal
- Azure Active Directory → Enterprise applications → New application → Create your own application
- Select the non-gallery option and name it “merchi.ai”
- On the app page → Single sign-on → SAML
- Basic SAML Configuration:
- Identifier (Entity ID):
https://api.merchi.ai/auth/v1/sso/saml/metadata - Reply URL (ACS URL):
https://api.merchi.ai/auth/v1/sso/saml/acs - Sign on URL:
https://app.merchi.ai/sign-in
- Identifier (Entity ID):
- User Attributes & Claims — add:
first_name→ user.givennamelast_name→ user.surnamejob_title→ user.jobtitlecompany→ user.companyname
- Group Claims — add a group claim:
- Source: Groups assigned to the application
- Source attribute: Group display name (not Object ID)
- Claim name:
merchi_groups
- Assign users to the application under Users and groups
- From SAML Signing Certificate, copy the App Federation Metadata Url and send it to merchi.ai
Okta
- Sign in to the Okta Admin Console
- Applications → Create App Integration → SAML 2.0
- Name the app “merchi.ai”
- SAML Settings:
- Single sign-on URL:
https://api.merchi.ai/auth/v1/sso/saml/acs - Audience URI (SP Entity ID):
https://api.merchi.ai/auth/v1/sso/saml/metadata - Name ID format: EmailAddress
- Application username: Email
- Single sign-on URL:
- Attribute Statements — add:
first_name→ user.firstNamelast_name→ user.lastNamejob_title→ user.titlecompany→ user.organization
- Group Attribute Statements — add:
- Name:
merchi_groups - Filter: matches your merchi.ai role groups
- Name:
- Assign the app to users or groups
- From the Sign On tab, copy the Metadata URL and send it to merchi.ai
What to Send merchi.ai
Once your SAML application is configured, send us:
- The IdP Metadata URL or Metadata XML file
- The email domain your users sign in with (e.g.
yourcompany.com) - The names of the groups you mapped to
merchi_groups(so we can confirm role mapping)
We will complete the connection on our side and confirm when SSO is live.
How Sign-In Works for Users
Once SSO is active:
- Go to
https://app.merchi.ai/sign-in - Click Sign in with SSO
- Enter their email address and click Continue with SSO
- They are redirected to your company’s login page
- After authenticating, they are redirected back to merchi.ai
On their first login, their account is created automatically and they are added to your workspace. On every subsequent login, their profile and role are refreshed from your directory.
Frequently Asked Questions
Do users still need a merchi.ai password? No. Once SSO is active for your domain, users sign in through your identity provider only.
What about MFA? MFA for SSO users is managed entirely by your identity provider. When a user signs in via SSO, they are redirected to your company login page — whatever MFA or conditional access policies you have configured there will apply. merchi.ai trusts the authentication your IdP performs. We recommend enabling MFA in your identity provider for all users who access merchi.ai.
What happens if a user is removed from our identity provider? They will not be able to sign in to merchi.ai. Their existing data is not deleted automatically — contact us if you need a user removed.
Can some users use SSO and others use a password? Yes. SSO is domain-based — users on your email domain are routed through SSO. Users on other domains can continue using password login.
What role will new users get by default?
Member access. If you configure role groups and map them via merchi_groups, users will receive the role matching their group instead.
Can we change a user’s role after they’ve signed in? Yes — either via the merchi.ai Team settings page, or by updating their group in your identity provider (takes effect on their next login).