See api-docs Menu
  1. Home >
  2. API >
  3. 2 >
  4. Smart MFA >
  5. Validate a User

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

https://<subdomain>/api/2/smart-mfa

Header Parameters

Authorization

required

string

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.

Content-Type

required

string

 Set to application/json.

Request Parameters

user_identifier

required

string

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

email

required for email mfa

string

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.

phone

required for sms mfa

string

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.

context

required

object

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.

risk_threshold

integer

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.

firstname

string

First name of the user.

lastname

string

Last name of the user.

expires_in

integer

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": "120.118.218.227",
    "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": "user@example.com",
  "context": {
    "ip": "120.118.218.227",
    "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

  • 200 OK
  • 400 Bad Request
  • 401 Unauthorized

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 120.118.218.227",
            "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"
    }
}

user_id

number

A unique identifier assigned to user by OneLogin.

risk

object

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.

mfa

object

  • 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

curl -XPOST 'https://<subdomain>.onelogin.com/api/2/smart-mfa' \
  -H 'Authorization: Bearer xxxxxxxxxxxxx' \
  -d '{
  "user_identifier": "unique-user-identifier-123455",
  "phone": "+15555555555",
  "context": {
    "ip": "120.118.218.227",
    "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.