Use this guide when your client's Login Experience is Application-controlled. For Journey-orchestrated clients, see Build the B2B journeys instead. Your application provides the screens, identifies the member's organization, and calls Mosaic's authentication APIs. Mosaic authenticates the member and issues tokens in that organization's context.
Complete the shared B2B setup through Set members, including:
- A Mosaic application and an Application-controlled client — see Configure app & client.
- Organizations associated with the application, with their member email domains registered — see Create organizations.
- Members with access to the application in the relevant organization — see Set members.
The authentication requests below run from your backend and use a client access token.
Establish which organization the member is signing in to before initiating member authentication. Your customer-facing application must supply this context; it cannot assume a default organization.
Applications usually identify the organization through one of these approaches:
- A dedicated subdomain or URL for each business customer.
- Their own mapping of customers to Mosaic organizations.
- Asking the member to choose an organization.
The Organizations API retrieves an organization by ID or name, and lists organizations filtered by name or application. It does not expose an endpoint or filter that maps an email domain to an organization. If your application uses email domains for routing, maintain that mapping in your own code or data.
Keep the resolved organization ID for the authentication request. If a member belongs to multiple organizations, your application also determines which one they are signing in to.
Your application decides which authentication operations to run and provides the screens for collecting credentials. It must handle the logic for each organization's authentication configuration, including authenticator registration and MFA where required.
Follow the integration guide for the methods your application uses, such as Email OTP, Passwords, or Email magic links. Those guides describe the method-specific sequence; supply the organization's ID as described below to authenticate a B2B member.
Pass the resolved ID as org_id in the backend authentication request. The OTP, password, and magic link authentication endpoints support this field for B2B member login.
For example, after sending an email OTP and collecting the code, send this JSON body to POST /v1/auth/otp/authenticate, using the header Authorization: Bearer <CLIENT_ACCESS_TOKEN>:
{
"identifier_type": "email",
"identifier": "member@agency.com",
"passcode": "<OTP_ENTERED_BY_MEMBER>",
"org_id": "<ORGANIZATION_ID>"
}Replace the identifier, passcode, and organization ID with the values for the current login. In this flow, org_id belongs in the OTP authentication request; the OTP send request does not accept it. See Login with Email OTP for the complete send-and-authenticate sequence.
After authentication succeeds, validate the returned tokens before granting access. Test the flow with members of the organizations your application serves, including a member with access to more than one organization, to verify that your application uses the intended organization context.