How to Integrate External Authenticator with Monosign Passwordless

Overview

This guide explains how an Identity Provider (IdP) integrates with Monosign for authentication using an external ("Service") authenticator. In this passwordless flow, Monosign does not validate a username/password pair — the IdP only identifies the user by username, and the actual authentication decision is delegated entirely to the external authenticator application, which the user approves or rejects through their registered device.

Step 1: Look Up the User

Before an authentication request can be created, the IdP must resolve the user's Monosign UserId from a username. Unlike a traditional login, this step does not validate a password and does not create a session — the user is only identified here; the actual authentication decision happens later, entirely through the external authenticator (Step 3).

Endpoint: {{Api Url}}/v1.4/users/lookup

Method: POST

Headers:

• Monosign-AppId: {{AppId}}

• Monosign-AppKey: {{AppKey}}

The App Key used here must have the System_API_Users_Lookup permission.

Request Body:

{
  "userName": "{UserName}"
}

Response includes:

• Data.List – an array of matching users. Use Data.List[0].Id as the UserId for subsequent calls.

  • If Data.List is empty, the user was not found — stop the flow and surface an appropriate error.

  • If Data.List contains more than one entry (the same username can exist across multiple sources), the IdP must disambiguate before continuing — e.g. by also matching on SourceName/SourceId in the response.

Step 2: Retrieve User Authenticator Information

Before initiating an authentication request, the Identity Provider (IdP) must retrieve the user's registered authenticators from Monosign. This operation returns all active authenticators associated with the user. Since a user may have multiple authenticators, the Identity Provider must identify the appropriate authenticator before initiating the authentication request.

Endpoint: {{Api Url}}/v1.3/mfa/options/{UserId}

Method: GET

Headers:

• Monosign-AppId: {{AppId}}

• Monosign-AppKey: {{AppKey}}

The App Key used here must have the System_API_MFA_Options permission.

Select the authenticator with Name property set to "Service". The Id value becomes the UserAuthenticatorId.

If no authenticator with Name = "Service" is present in the list, the user has not enrolled the external authenticator — stop the flow and surface an appropriate error rather than calling Step 3 with an empty/invalid id.

Step 3: Initiate Authentication Request

Once the correct UserAuthenticatorId is known, the IdP creates a new authentication transaction. Monosign waits up to 60 seconds for the user to respond through the external authenticator application. If the user approves or rejects within the first 5 seconds, the API responds immediately with the outcome; otherwise, a UsageId is returned so the IdP can poll for the result (Step 4).

Endpoint: {{Api Url}}/v1.3/mfa/request/{UserAuthenticatorId}

Method: POST

Headers:

• Monosign-AppId: {{AppId}}

• Monosign-AppKey: {{AppKey}}

The App Key used here must have the System_API_MFA_CreateAuthenticationRequest permission.

Request Body:

{
  "userId": "{UserId}",
  "isPasswordless": true,
  "userIp": "192.168.55.90"
}

• userId – the UserId resolved in Step 1. Required so Monosign can validate it belongs to the UserAuthenticatorId in the URL.

• isPasswordless: true – required since this flow has no login session. Without it, Monosign rejects the request for missing a session; with it, Monosign creates one for this request on the fly.

• userIp – the end user's IP address, recorded on the authentication audit trail.

Possible Responses:

• Code 10117 – MFA Verified (approved)

• Code 10118 – MFA Declined (rejected)

• Code 499 – No response within 5 seconds (returns UsageId for polling)

Step 4: Check Authentication Request Status

If the user did not respond within the first 5 seconds (Code 499), the IdP polls this endpoint using the UsageId returned by Step 3. The authentication request remains valid for 60 seconds from creation; the IdP should continue polling periodically until the user approves, rejects, or the request expires.

Endpoint: {{Api Url}}/v1.3/mfa/request/{{UserAuthenticatorId}}/{{UsageId}}

Method: POST

Headers:

• Monosign-AppId: {{AppId}}

• Monosign-AppKey: {{AppKey}}

Same App Key permission as Step 3: System_API_MFA_CreateAuthenticationRequest.

Request Body:

{
  "userId": "{UserId}",
  "isPasswordless": true,
  "userIp": "XXX.XXX.XX.XX"
}

As in Step 3, userId and isPasswordless: true are required on every poll request since there is no session.