API Service Authenticator

Applies to Monosign v2026.11 and later. For IT and IAM administrators.

1. What it is

The API Service Authenticator connects Monosign to a verification service you already have: an SMS gateway, a token server, an in-house OTP service, or any other system with an HTTP API. Monosign calls your service to start a verification and to check the answer. Your users see a normal Monosign sign-in page.

You can define one or several of them. Each one has its own address, keys and behaviour, so different groups of users can use different services.

With a policy and a flow you can also change who receives the code. For example, a contractor signs in, and the code goes to their sponsor or manager, who passes it on.

You want	Go to
Connect one external service	Section 3
Connect a second or third service	Section 4
Ask a group of users for this factor	Section 6
Send the code to another person, through another channel	Section 7

2. Before you start

You need:

An administrator account that can manage Authenticators, Policies and Flows in Monosign Management.
From the owner of the external service:
- the address (URL) that starts a verification (for example, sends an SMS), if the service has one;
- the address that checks a code or an approval;
- the keys or passwords the service asks for;
- an example of a successful answer and of a failed answer (JSON).
The Monosign servers must be able to reach the service over the network.

The service must answer in JSON for Monosign to read the result. If it answers with an HTTP status only (no body), see the option Accept Validation on HTTP Success in 3.6.

3. Set up the API Service Authenticator

3.1 Open it

Sign in to Monosign Management.
Go to Security → Authenticators.
On the row API Service Authenticator, select Configure.

The page has these tabs: General, Service Settings, Additional Information, Usage.

3.2 General tab

Field	What to enter
Status → Enabled	Leave off until the setup is tested. Users only see enabled authenticators.
Name	The name your users see, for example the name of your SMS service.
Description	A short text your users see.

3.3 Service Settings tab

This tab has its own sub-tabs. Fill them from left to right.

Sub-tab	Purpose	Needed?
General	Description (shown on the enrollment page) and Help (shown in the help panel).	Optional
Parameters	Named values such as API users, keys and secrets. You use them in every endpoint as `{{Parameters.Key}}`.	Recommended
Enrollment	A call made when a user adds this authenticator.	Only if the service must register the user
Request	The call that starts a verification, for example "send the SMS".	If the service sends something
Validation	The call that checks the code or the approval.	Yes, in almost every setup
Unenrollment	A call made when a user removes this authenticator.	Optional
Options	Limits, polling and logging.	Review once

Each of Enrollment, Request, Validation and Unenrollment has a switch at the top. Turn it on to see the endpoint fields.

Parameters

Select Add.
Enter a Key (for example ApiKey) and a Value.
Tick Is Encrypted for every secret. An encrypted value is stored protected and is never shown again. To keep it later, leave the value blank; to change it, type the new value.

3.4 Endpoint fields

Enrollment, Request, Validation and Unenrollment use the same fields.

Field	What to enter
Url	The address of the service call. Select Help to see the values you can insert.
Method	`GET`, `POST`, `PUT` or `PATCH`.
Content Type	Choose JSON. Monosign reads the answer only when this is JSON.
Body Template	The body Monosign sends. Insert values with `{{...}}`, see Section 10.
Headers	Add one row per header. Tick Is Encrypted for secrets, or use `{{Parameters.Key}}`.
Identifier Path	Where the service's own transaction id is in the answer, for example `$.transactionId`. Monosign keeps it, and you can send it back later as `{{ExternalReferenceId}}`.
Identifier Expression	Optional regular expression the id must match.
Validation Path	Where the result is in the answer, for example `$.status`.
Validation Expression	Regular expression for a successful result, for example `^ok$`. Empty means "any value is fine, it only has to be there".
Cancel Path / Cancel Expression	Where and how the service says the user declined (push approval services).
Message Path	Where the service's own error text is, for example `$.message`. Monosign shows this text to the user when a code is refused.
Input Requirement	Turn on Enabled and select Add to design the fields the user fills at this step (Name, Title, Type, Default Value, Required). Use a value as `{{Form.Name}}`.
Message / Additional Message	Texts shown to the user during this step.

Paths are case-sensitive: $.status and $.Status are different. Expressions are not case-sensitive.

For a code the user types, add one input on the Validation endpoint with Name Code, Type OTP, Required Yes, and send it in the body as {{Form.Code}}.

3.5 Three common setups

Setup	Request	Validation	Validation Polling (Options)
The service sends a code, the user types it	On	On, with a `Code` input	Off
Code only: nothing is sent at sign-in; the user types a code they get another way	Off	On, with a `Code` input	Off
Approval in the service's own app (push)	On	On, no input	On

Example for the first setup:

Request

Field	Example
Url	`https://sms.example.com/api/otp/send`
Method	`POST`
Content Type	`JSON`
Headers	`X-Api-Key` = `{{Parameters.ApiKey}}`
Body Template	`{ "user": "{{UserName}}", "phone": "{{Profile.MobilePhone}}" }`
Identifier Path	`$.transactionId`
Validation Path / Expression	`$.status` / `^sent$`

Validation

Field	Example
Url	`https://sms.example.com/api/otp/verify`
Method	`POST`
Content Type	`JSON`
Headers	`X-Api-Key` = `{{Parameters.ApiKey}}`
Input Requirement	Enabled; input Name `Code`, Title `Verification code`, Type `OTP`, Required `Yes`
Body Template	`{ "transactionId": "{{ExternalReferenceId}}", "code": "{{Form.Code}}" }`
Validation Path / Expression	`$.result` / `^ok$`
Message Path	`$.message`

3.6 Options

Option	Meaning
Max Try Count	How many times the user may submit a code for one verification. After that the user signs in again. `0` means no limit.
Validate OTP First	Monosign checks the typed code itself first; if that fails and a Validation endpoint exists, it asks the service.
Enable Debug Logging	Writes every call to the service, with full content, to the application log. Turn it on only while you set up or investigate, then off: the content includes codes and user identifiers.
Accept Validation on HTTP Success	For services that answer with a status code only. Turn it on only after you confirm the service answers a wrong code with an unsuccessful status. Otherwise every code is accepted.
Allow Untrusted Certificates	Skips the certificate check. Use it for test environments only.
Validation Polling	Monosign asks the Validation endpoint again and again whether the user approved. Turn it off when the user types a code.
Polling Interval (seconds)	1–60, default 3. Shown when polling is on.
Poll Before Input Submission	Only for services that accept repeated status checks. Keep it off for services that count an empty check as a failed attempt.

3.7 Save, test, enable

Select Save.
Open General, turn Status → Enabled on, and select Save. Users can only add an enabled authenticator. Until a policy asks for it, nobody is forced to use it.
Enroll one test user (Section 5).
Select Test. In Test API Service Authenticator, choose the User, open the tab of the endpoint and select Run … test. The test uses the saved settings, so save first. These are real calls: the service may send a real SMS. You see what was sent, what came back, and how each path and expression was read.
Sign in once as the test user and type a right code and a wrong code (Section 8).

Test judges the answer of the service the same way a sign-in does, and tells you why when a sign-in would fail. Run Request first and then Validation: the Validation test continues the session of the Request test. Still finish with one real sign-in (step 5) before you ask other users to enroll.

4. Add a second API Service Authenticator (or more)

Use this when different users must use different services. For example, employees use one SMS service and contractors use another.

Go to Security → Authenticators.
Select Add API Service Authenticator.
Enter a Title and select Add.
The new authenticator opens. Set it up as in Section 3, then enable it.

Good to know:

You can add as many as you need. Repeat the steps for each one.
A new one starts disabled and empty. Nothing is copied from the first one.
The title must be new. Monosign builds an internal name from the title (letters and digits only), and that name must also be new. If it is not, Monosign asks you to choose another title.
Each user uses the authenticator they enrolled in. A policy can name which one to ask for (Section 6).
To stop using one, turn its Status off.

5. Users enroll

A user must add the authenticator before Monosign can ask for it.

The user signs in to the Monosign account portal.
Security → Multi Factor Security opens the page Multi-Factor Authentication.
On the card of your authenticator, the user selects Configure.
The user fills the fields you designed on the Enrollment endpoint (if any) and selects Validate and Save.

You can see a user's authenticators in Management: Users → the user → tab Authenticators.

6. Ask for it at sign-in with a policy

Without a policy, Monosign asks a user for the factor they chose as default. A policy lets you decide: "these users must pass this authenticator".

Go to Security → Policies and select Add New.
Tab Overview:
- Type: Authentication (it cannot be changed later).
- Name, Description, Priority.
- Enabled: on.
Tab Scope: add at least one scope to say who the policy is for. Common choices: User Group, Specific User, User Source, Application.
Tab Actions: select Add an action, then Add another action for each next step, in the order of the table below.
Select Save.

#	Action	Settings
1	Authentication Factor	Type `Primary`, Factor `Username and Password`
2	Authentication Factor	Type `Secondary`, Factor = your authenticator
3	Allow Access	—

In the Factor list, the built-in one is shown as API Service Authenticator. The ones you added are shown with their own titles.

Choose Type Secondary for the service factor. Primary means "instead of the password".

7. Send the code to another person (policy + flow)

7.1 How it works

Normally the service sends the code to the user who signs in. In this setup nothing is sent to that user. A flow delivers the code to another person, through the channel you choose, and that person passes it on.

User types the password
        │
        ▼
Policy step "Execute Flow"  ──►  Flow starts
        │                          1. (optional) the user fills a form, e.g. picks a sponsor
        │                          2. the flow reads the sign-in code
        │                          3. the flow delivers it: e-mail, approval, or a web request
        ▼
Policy step "Authentication Factor" with "Do Not Send Notification"
        │
        ▼
User types the code received from the other person  ──►  signed in

Two switches make this work:

Execute Flow in the policy starts your flow after the password is correct.
Do Not Send Notification on the factor step stops every message to the user: no SMS, e-mail, phone call, push, and no call to the Request endpoint of the API Service Authenticator.

Flows run in the Monosign Service component. It must be running.

7.2 Create the flow

Go to Workflows → Flows and select Add New.
Tab Overview: enter a Title and set Trigger Type to Policy. Only Policy flows can be chosen in a policy.
Tab Flow: add the steps below with the plus button (Add Step), then draw the lines Start → step 1 → step 2 → … → End.
Select Save.

Step A (optional) — Form: the user says who should get the code

Setting	Value
Step type	Form
Form	A form you created under Workflows → Forms, with a field for the other person (for example their phone number)
Approvers	Starter Approval — the user who signs in fills the form on the sign-in page
Exported Variable Name	Keep `form`

The sign-in page also asks the user for a reason (Why are you taking this action?). To leave that box out, turn on Skip Request Description on the flow's Overview tab.

Step B — Code: read the sign-in code

Setting	Value
Step type	Code
Code	`return context.Workflow.StartedByUser.GetAuthenticatorCode(context.Workflow.Login.SelectedMfaFactor);`
Exported Variable Name	`LoginCode`

You do not need to write more code than this one line. The same example is on the screen under Context Reference.

Step C — Deliver the code. Choose one.

You want	Step type	Settings
E-mail to fixed people	Notification	Users and/or Additional E-Mail Addresses; Content = a content whose text includes `{{context.Data.LoginCode}}`; keep Notify Starter off
The manager approves and gets the code	Approval	Approvers → Manager Approval (or Groups); Actions → Add Action → When `On Step Assigned`, Content = a content whose text includes `{{context.Data.LoginCode}}`
SMS or any other system, to the person from the form	Web Request	Url, Method, Body, Headers of your SMS or messaging service. Insert `{{context.Data.LoginCode}}` and the form field, for example `{{context.Data.form.SponsorPhone}}`

A form field is used by its name on the form: a field named SponsorPhone in a form step with the variable name form is {{context.Data.form.SponsorPhone}}.

Contents are created under System → Contents. Example text:

Sign-in code for {{UserName}}: {{context.Data.LoginCode}}

With an Approval step, Approve continues the sign-in and Reject denies it.

Notify Starter sends the e-mail to the user who signs in. Keep it off, or the user gets their own code.

7.3 Create the policy

Create the policy as in Section 6, with these actions in this order:

#	Action	Settings
1	Authentication Factor	Type `Primary`, Factor `Username and Password`
2	Execute Flow	Flow = the flow from 7.2
3	Authentication Factor	Type `Secondary`, Factor = your authenticator, Do Not Send Notification on
4	Allow Access	—

A policy can contain one Execute Flow step.

7.4 What the user sees

The user enters user name and password.
If the flow has a form, the user fills it on the sign-in page.
The page shows Approval Required and Waiting for approval... while the flow runs.
The page asks for the code: Enter the verification code provided to you. There is no "send again" button, because nothing was sent to this user.
The user types the code they received from the other person and is signed in.

If the code is wrong, the page says Your authentication code is wrong. After too many wrong codes the user starts again from the password; the flow runs again and delivers a new code. If an approver rejects, the page says Your sign-in request was not approved.

7.5 Variant: the external service creates the code

If your service creates and sends its own codes, let the flow ask the service to send the code to the other person:

In the flow, skip Step B. Use a Web Request step that calls the service's "send" address with the other person's number.
Keep the Validation endpoint of the authenticator on. Monosign asks the service whether the typed code is right.
The policy is the same as in 7.3.

7.6 Without a flow: code only

If you only want "never send anything, the user always types a code from another source", you do not need a policy. Turn the Request endpoint off and keep Validation on (3.5, setup "Code only"). This applies to every sign-in with that authenticator, including RADIUS.

8. Check that it works

Check	Expected
Test on the authenticator page	Each check shows the path, the value found and a successful result
Sign in as a test user	The page asks for the code; the right code signs the user in
Type a wrong code	Your authentication code is wrong., or the service's own text if you set Message Path
Authenticator page → tab Usage	One row per verification, with its state
Audit records of the user	Sign-in attempts and every wrong code are listed
Sponsored sign-in (Section 7)	The other person receives the code; the user who signs in receives nothing

9. Troubleshooting

What you see	Likely cause	What to do
Unable to process your request. Service returned an error.	The service is not reachable, answered with an error, or the answer did not match Validation Path / Identifier Path	Run Test; check the address, the keys and the paths (case-sensitive)
Every code is refused	Content Type of the Validation endpoint is not `JSON`, Validation Path is empty, or the expression does not match the real answer	Compare with a real answer in Test
Every code is accepted	Accept Validation on HTTP Success is on and the service answers a wrong code with a successful status	Turn the option off and use Validation Path
The user is not asked for this factor	The user did not enroll, the authenticator is disabled, or the policy scope does not include the user	Check Section 5, Status, and the policy Scope
Your new authenticator is not in the policy Factor list	It was added before the policy page was opened	Reload the policy page
The Flow list in Execute Flow is empty	No flow has Trigger Type `Policy`	Set it on the flow's Overview tab
The user still receives the SMS	Do Not Send Notification is off on the factor step	Turn it on (7.3)
The other person receives an empty code	The factor step is Type `Primary`, Do Not Send Notification is off, or the variable name differs from `LoginCode`	Check 7.2 Step B and 7.3
The sign-in stays on Waiting for approval...	Nobody approved yet, or the Monosign Service component is not running	Check the flow item under Workflows, and the Service component
Sign-In Not Approved without anyone rejecting	A flow step failed all its retries, so the flow was cancelled	Open the flow item under Workflows, look at the failed step, fix the step

While you investigate, turn Enable Debug Logging on (3.6) and turn it off afterwards.

10. Reference: values you can use

In the authenticator endpoints (Url, Body Template, Headers):

Value	Meaning
`{{UserId}}`	The user's identifier
`{{UserName}}`	The user's user name
`{{Email}}`	The user's e-mail
`{{UserSource}}`	The user's source
`{{Profile.*}}`	A profile property, for example `{{Profile.FirstName}}`, `{{Profile.MobilePhone}}`
`{{UsageId}}`	The identifier of this verification
`{{Value}}`	The code Monosign generated for this verification
`{{ExternalReferenceId}}`	The service's transaction id, taken from the Request answer with Identifier Path
`{{Parameters.*}}`	A value from the Parameters tab, for example `{{Parameters.ApiKey}}`
`{{Form.*}}`	A field the user filled, designed under Input Requirement, for example `{{Form.Code}}`

In flow steps (contents, Web Request Url / Body / Headers):

Value	Meaning
`{{context.Data.LoginCode}}`	The sign-in code read by the Code step (the name you gave in Exported Variable Name)
`{{context.Data.form.FieldName}}`	A field of the form step
`{{UserName}}`	The user who signs in (in contents)