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>.onelogin.com/api/2/smart-mfaHeader Parameters
Authorization required string | Set to Set 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 |
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. |
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:
|
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"
}
}
```xml
<p>Minimum required fields for Email based MFA</p>
```json
{
"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"
}
}
```html
<h2 id="sampleresponse">Sample Response</h2>
<div class="tab-group">
<ul class="tab-links">
<li class="t-link status-200 active" data-tab="1">200 OK</li>
<li class="t-link status-400" data-tab="2">400 Bad Request</li>
<li class="t-link status-401" data-tab="3">401 Unauthorized</li>
</ul>
<div class="tab-views">
<div class="t-view active" data-tab="1">
Success. MFA Token has been sent.
```javascript
{
"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"
}
}
```html
<table cellpadding="10">
<tbody>
<tr>
<td align="right" valign="top">
**user_id**
number
</td>
<td valign="top">
A unique identifier assigned to user by OneLogin.
</td>
</tr>
<tr>
<td align="right" valign="top">
**risk**
object
</td>
<td valign="top">
The level of risk determined for the user on this request.
<ul>
<li><strong>score</strong> - A value between 0 (low risk) and 100 (high risk)</li>
<li><strong>reasons</strong> - Array of strings that represent the main reasons that the risk was scored the way it was.</li>
</ul>
</td>
</tr>
<tr>
<td align="right" valign="top">
**mfa**
object
</td>
<td valign="top">
<ul>
<li><strong>otp_sent</strong> - Boolean value to indicate if a token has been sent or not.</li>
<li><strong>state_token</strong> - When a token is sent use this state token to verify the token in <a href="/api-docs/2/smart-mfa/validate-user">Step 2 - Verify Token</a>.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</div>
<div class="t-view" data-tab="2">
```json
{
"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"
}