See api-docs Menu

Validate a User

Early Preview

This API is in early preview and may be subject to change.

Use this API to validate a users risk and send an MFA token via Email or SMS when the risk is above an acceptable threshold.

This API takes care of registering new users as well as validating returning users.

It is recommended that you use this flow immediately after you have succesfully authenticated a users password but before you create a session and let them into your application.

It is assumed that you already a user database and a way to authenticate username/password. If you are looking for a solution that provides username/password authentication as well as MFA then we have other authentication options for you.

Resource URL


Header Parameters




Set to bearer:<access_token>.

Set <access_token> to the access token you generated using the Generate Token API.

The access token must have been generated using an API credential pair created using the scope required to call this API. This API must can be called using the Manage All scope.




Set to application/json.

Request Parameters




Either a unique ID, email address or username. Must be a unique identifier for the user.


required for email mfa


Email for sending the token. The same email address must always be used for a given user_identifier. If the users email has changed you must use the Update User API to update it.


required for sms mfa


E.164 formatted phone number for sending the token. The same phone number must always be used for a given user_identifier. If the users phone number has changed you must use the Update User API to update it.




An object containing information about the users current device, location and session.

The available object parameters are:

  • user_agent - required The user_agent of the browser.
  • ip - required The IP address of the user.
  • session_id - A persistent session identifier for the for the user.
  • device_id - A mobile device id or other type of unique identifier for a device.
  • device_fingerprint - A unique device fingerprint for the user web browser.



Defaults to 50. The risk_score level that will trigger an MFA token to be sent to the user.

If risk is greater than or equal to this value then a MFA token will be sent.



First name of the user.



Last name of the user.



Optional. Sets the window of time in seconds that the token must be verified within.

Defaults to 480 seconds (8 minutes). Max 900 seconds (15 minutes).

Sample Request Body

Minimum required fields for SMS MFA

  "user_identifier": "unique-user-identifier",
  "phone": "+1555555555",
  "context": {
    "ip": "",
    "user_agent": "Mozilla/5.0 (Windows; U; Windows NT 6.0) AppleWebKit/531.1.0 (KHTML, like Gecko) Chrome/21.0.843.0 Safari/531.1.0"

Minimum required fields for Email based MFA

  "user_identifier": "unique-user-identifier-12345",
  "email": "",
  "context": {
    "ip": "",
    "user_agent": "Mozilla/5.0 (Windows; U; Windows NT 6.0) AppleWebKit/531.1.0 (KHTML, like Gecko) Chrome/21.0.843.0 Safari/531.1.0"

Sample Response

Success. MFA Token has been sent.

    "user_id": 60254824,
    "risk": {
        "score": 93,
        "reasons": [
            "Chrome on Windows is used infrequently",
            "Kaohsiung City, Kaohsiung, Taiwan is a new location",
            "Taiwan is a new location",
            "Chrome on Windows has not been used before",
            "Accessed from a new IP address",
            "Accessed from a new browser session",
            "Infrequent access from",
            "Infrequent access from Kaohsiung City, Kaohsiung, Taiwan",
            "Infrequent access from Taiwan",
            "Infrequent access using Chrome on Windows",
            "Low trust for session",
            "Browser Cookie Expected"
    "mfa": {
        "otp_sent": true,
        "state_token": "67ff7e91-ec38-467d-b7df-c0f4f61efd73"



A unique identifier assigned to user by OneLogin.



The level of risk determined for the user on this request.

  • score - A value between 0 (low risk) and 100 (high risk)
  • reasons - Array of strings that represent the main reasons that the risk was scored the way it was.



  • otp_sent - Boolean value to indicate if a token has been sent or not.
  • state_token - When a token is sent use this state token to verify the token in Step 2 - Verify Token.

    "name": "BadRequestError",
    "message": "Parameter phone does not match users phone number"
    "name": "BadRequestError",
    "message": "Parameter email or phone not provided"
    "name": "BadRequestError",
    "message": "Parameter context must be included and contain user_agent and ip"

Invalid API Key

Sample Code


curl -XPOST 'https://<subdomain>' \
  -H 'Authorization: Bearer xxxxxxxxxxxxx' \
  -d '{
  "user_identifier": "unique-user-identifier-123455",
  "phone": "+15555555555",
  "context": {
    "ip": "",
    "user_agent": "Mozilla/5.0 (Windows; U; Windows NT 6.0) AppleWebKit/531.1.0 (KHTML, like Gecko) Chrome/21.0.843.0 Safari/531.1.0",

Postman Collection

Replace sample variables indicated by {{ }} with your actual values.

Download for the Smart MFA API

Have a Question?

Found a problem or a bug? Submit a support ticket.

Looking for walkthroughs or how-to guides on OneLogin's user and admin features? Check out the documentation in our Knowledge Base.

Have a product idea or request? Share it with us in our Ideas Portal.