Sign up
Documentation menu

Single Sign-On (SSO) with Microsoft Entra ID

ConvertAPI supports single sign-on (SSO) with Microsoft Entra ID (formerly Azure Active Directory). Your team signs in with the work accounts they already use, your organization's policies such as multi-factor authentication and Conditional Access apply, and you decide who has access in Microsoft Entra ID rather than in ConvertAPI.

SSO is available on the Enterprise plan and during the free trial, so you can set it up and try it before you buy.

How it works

  1. On the sign-in page, open the SSO tab and click Continue with Microsoft Entra ID.
  2. Microsoft asks for your work or school account and applies your organization's sign-in rules (MFA, Conditional Access, device policies).
  3. Microsoft sends you back to ConvertAPI, signed in to the ConvertAPI account with the same email address as your Microsoft account.

Things to know:

  • Work and school accounts only. Personal Microsoft accounts (outlook.com, hotmail.com, live.com) are not supported.
  • Matching is by email address. Your Microsoft account needs an email address on a domain your organization has verified in Microsoft Entra ID, and it must be the email address of your ConvertAPI account.
  • SSO does not create accounts. People join your team through an invitation first (see Setting up SSO for your organization below).
  • What ConvertAPI uses from Microsoft: your name, your email address, your organization's tenant ID and whether the email address is verified. ConvertAPI never sees your Microsoft password, keeps no Microsoft tokens and gets no access to your files, mail or directory.

Two kinds of team members

Regular members can sign in with any method: email and password, Google, GitHub, or the SSO tab if their Microsoft email matches their ConvertAPI email.

SSO-only members are invited with the Microsoft SSO switch turned on. For them:

  • Microsoft Entra ID is the only way to sign in. Email and password, Google and GitHub are refused.
  • They have no ConvertAPI password, so there is no password reset for them.
  • Two-factor authentication follows your organization's Microsoft policies. ConvertAPI's own two-factor setup is not used.
  • Their email address cannot be changed in ConvertAPI, because it is how Microsoft sign-in finds them.
  • The team list marks them with an SSO badge.

Use SSO-only members when your organization requires that everyone signs in through Microsoft Entra ID, for example so that disabling someone in Entra ID also stops them signing in to ConvertAPI. The account owner always stays a regular member, because only invited members can be SSO-only.

Setting up SSO for your organization

1. Create your ConvertAPI account

Sign up with your work email address. SSO works during the trial, so you can set everything up before choosing a plan.

2. Allow ConvertAPI in Microsoft Entra ID

The first time someone from your organization signs in with Microsoft, Microsoft asks for consent to let ConvertAPI sign them in and read their basic profile (name and email address). Nothing else is requested.

Many organizations only let administrators approve new applications. In that case people see Need admin approval, and an administrator of your Microsoft Entra tenant approves ConvertAPI once for everyone. The simplest way is the approval link:

  1. Open https://www.convertapi.com/sso/microsoft/admin-consent, or send it to your administrator. It is also on the Team Members page, under the invite form, and in the message people see when they come back from Need admin approval. The administrator does not need a ConvertAPI login.
  2. They sign in to Microsoft with at least the Cloud Application Administrator role and accept.
  3. ConvertAPI confirms that it is approved for your organization. Everyone can now sign in through the SSO tab.

Two other ways, if your administrator prefers them:

  • A Global Administrator or Privileged Role Administrator signs in to ConvertAPI through the SSO tab. On Microsoft's consent screen, they tick Consent on behalf of your organization and accept. They do not need a ConvertAPI login for this, because Microsoft records the consent before it sends them back to ConvertAPI.
  • An administrator with at least the Cloud Application Administrator role opens the Microsoft Entra admin center, goes to Enterprise applications, selects ConvertAPI, then Permissions, and clicks Grant admin consent. ConvertAPI is only listed there once someone in your organization has consented to it, so use the approval link if it is missing.

Tip: The consent screen names the application ConvertAPI, published by UAB ConvertAPI with Microsoft's verified publisher badge.

3. Optional: choose who may use ConvertAPI

By default, anyone in your organization can sign in with Microsoft to an account whose email they own. To limit this to selected people:

  1. In the Microsoft Entra admin center, open Enterprise applications, then ConvertAPI.
  2. Under Properties, set Assignment required? to Yes and save.
  3. Under Users and groups, add the users or groups who may use ConvertAPI. Assigning groups needs Microsoft Entra ID P1 or P2.

Everyone else is then stopped by Microsoft before they reach ConvertAPI. With assignment required, Microsoft also insists on the administrator consent from step 2, even where users could otherwise consent for themselves.

4. Check your users' email addresses

ConvertAPI finds each person by the email address Microsoft sends, which is the Email field of the user in Microsoft Entra ID. This is not their sign-in name (the user principal name). The two often look the same, but they are separate fields.

  • Users with a Microsoft 365 mailbox (Exchange Online) have the Email field filled in automatically. Nothing to do.
  • Users without a Microsoft mailbox, for example when your email runs on Google Workspace or another provider, often have an empty Email field, even though they sign in as name@yourcompany.com. Microsoft then sends no email address, and ConvertAPI refuses the sign-in with "Your Microsoft account has no verified email address."

To check or fix it, open the Microsoft Entra admin center, go to Users, select the user, then Edit properties > Contact information, and fill in Email with their work address. It must be on a domain verified in your tenant (Domain names) and the same address you invite them with in ConvertAPI. For many users, set the mail property in bulk with Microsoft Graph or PowerShell.

5. Invite your team

  1. Open Team Members in your ConvertAPI dashboard.
  2. Enter the person's work email address and choose a role.
  3. Turn on the Microsoft SSO switch in the Sign-in column to make them an SSO-only member, or leave it off for a regular member.
  4. Click Send invite.

The invitee gets an email with a link that is valid for 7 days. For an SSO invitation, the link opens a Join your team page with a single Continue with Microsoft Entra ID button. They must sign in with the Microsoft account for the exact address you invited. If they use a different account, ConvertAPI tells them which address the invitation was sent to.

Tip: If an invitation link no longer works, send a new invitation. Remove the old one first if the team list still shows it as pending, because each address can have only one pending invitation.

Changing an existing member

The SSO setting of a member cannot be switched later. To turn a regular member into an SSO-only member, or the other way round, remove the member from the team list and invite them again with the Microsoft SSO switch on or off.

Removing access

  • In Microsoft Entra ID: disable the user, or remove them from the ConvertAPI assignment if you use Assignment required. They can no longer sign in with Microsoft. For SSO-only members this closes the only way in.
  • In ConvertAPI: remove the member from the team list. This deletes their ConvertAPI login and frees their seat.

Both stop new sign-ins, but neither ends a session that is already open. An open session stays signed in while it is in use, and ends at the latest 14 days after it was last used. ConvertAPI cannot end it sooner.

API tokens and the master token belong to your ConvertAPI account, not to a team member. Removing someone does not revoke a token they copied. Replace any token they had access to on the Authentication page, and reset the master token if they were an admin.

Plans and SSO

SSO works on the Enterprise plan and during the trial, active or expired. On other plans, Microsoft sign-in is refused with "SSO is available on the Enterprise plan."

If your account moves to a plan without SSO, SSO-only members can no longer sign in, because they have no other way in. Contact support and we will help you move them to regular members.

Troubleshooting

Message or situation What to do
Need admin approval on Microsoft's page An administrator approves ConvertAPI once for the organization, most simply with the approval link (step 2 above).
Your Microsoft account has no verified email address. Microsoft sent no email address, or one on a domain not verified in your tenant. Usually the user's Email field in Microsoft Entra ID is empty because they have no Microsoft mailbox. Fill it in with their work address (step 4).
SSO needs a work or school Microsoft account. You signed in with a personal Microsoft account. Sign in with the account your organization gave you.
You don't have a ConvertAPI account with this email. Invite the person to your team first, with the same email address as their Microsoft account.
SSO is available on the Enterprise plan. Your account is on a plan without SSO. Move to Enterprise, or sign in another way.
This invitation was sent to ... Sign in with the Microsoft account for the invited address, or ask your admin to invite the address you use.
Your organization's plan doesn't include SSO. The account lost SSO after the invitation was sent. Ask your admin to move to Enterprise, or to invite you again with the Microsoft SSO switch off.
Your organization signs in with Microsoft Entra ID. You are an SSO-only member: use the SSO tab instead of email, Google or GitHub.
Sign-in was cancelled. Microsoft sign-in was cancelled or consent was declined. If Microsoft said an administrator must approve ConvertAPI, send your administrator the approval link in the message (step 2). Otherwise try again.
Microsoft sign-in didn't complete. Try again. If it keeps happening, contact support.
Nothing was approved (after the approval link) The approval was declined on Microsoft's page, or the account has no administrator role. Try again as at least a Cloud Application Administrator.
This approval link has expired The approval took longer than 15 minutes, or the page was opened again. Open the approval link again.
Microsoft says personal accounts can't be used Use your work or school account. Personal Microsoft accounts are not supported.

Still stuck? Contact support with the message you see and the email address you sign in with.