See api-docs Menu

Verify Factor

Verify a one-time password (OTP) value provided for multi-factor authentication (MFA).

This API is used in close conjunction with the Create Session Login Token API, when MFA is required.

For detailed usage flows and examples of how to use this API and the Create Session Login Token API to log a user in, see Logging a User In Via API.

Delegated Authentication

You can also use this API to delegate authentication of a user to OneLogin when MFA is required. When you want to simply authenticate a user in OneLogin and MFA is required, you can just treat the token returned by the Verify Factor API in the 200 OK - Success message as a confirmation that the user has been authenticated. The session token itself is not used.

Likewise, you can use the 401 - Unauthorized status code to indicate that a user could not be authenticated.

Resource URL

https://api.<us_or_eu>.onelogin.com/api/1/login/verify_factor

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 can be called using any the Authentication Only, Manage users, and Manage All scope.

Content-Type

required

string

Set to application/json.

Request Parameters

device_id

required

string

Provide the MFA device_id you are submitting for verification. The device_id is supplied by the Create Session Login Token API

state_token

required

string

Provide the state_token associated with the MFA device_id you are submitting for verification. The state_token is supplied by the Create Session Login Token API.

otp_token

string

Provide the OTP value for the MFA factor you are submitting for verification.

For some MFA factors; such as OneLogin OTP SMS, which requires the user to request an OTP; the otp_token value is not required, and if not included, returns a 200 OK - Pending result. You’ll make a subsequent Verify Factor API call to provide the otp_token value once it has been provided to the user.

In the case of other MFA factors; such as Google Authenticator, which immediately provide an OTP value to the user; the otp_token value is required as it is immediately available to the user

Sample Request Body

{
    "device_id": "111142666",
    "state_token": "xxx98ac9cb3a47b45f2ccedeabad8ed618a6b6d8831",
    "otp_token": "876543"
}

Sample Response

This is what a 200 OK response looks like when authentication is pending.

{
    "status": {
        "type": "success",
        "code": 200,
        "message": "SMS token sent to your mobile device. Authentication pending.",
        "error": false
    }
}

This is what a 200 OK response looks like when the user has been authenticated.

{
    "status": {
        "type": "success",
        "code": 200,
        "message": "Success",
        "error": false
    },
    "data": [
        {
            "return_to_url": null,
            "user": {
                "username": "jhasenfus",
                "email": "jennifer.hasenfus@onelogin.com",
                "firstname": "Jennifer",
                "lastname": "Hasegawa",
                "id": 88888888
            },
            "status": "Authenticated",
            "session_token": "xxxxxxxxx8a4c07773a5454f946",
            "expires_at": "2016/01/26 02:21:47 +0000"
        }
    ]
}
{
    "status": {
        "type": "bad request",
        "message": "State token is invalid or expired",
        "code": 400,
        "error": true
    }
}

{
    "status": {
        "type": "error",
        "message": "state_token is empty",
        "error": true,
        "code": 400
    }
}

{
    "status": {
        "type": "error",
        "message": "device_id is empty",
        "code": 400,
        "error": true
    }
}

Typically, the following error means that the device_id value is invalid.

{
    "status": {
        "type": "bad request",
        "message": "Factor could not be found",
        "code": 400,
        "error": true
    }
}

Typically, the following error means that your Authorization header value is missing or incorrectly formatted. Your Authorization header format should be bearer:<access_token>.

{
    "status": {
        "error": true,
        "code": 400,
        "type": "bad request",
        "message": "Authorization Information is incorrect"
    }
}

Typically, the following error means that your otp_token is invalid.

{
    "status": {
        "type": "Unauthorized",
        "code": 401,
        "message": "Failed authentication with this factor",
        "error": true
    }
}

Typically, the following error means that the access token is invalid.

{
    "status": {
        "error": true,
        "code": 401,
        "type": "Unauthorized",
        "message": "Authentication Failure"
    }
}

Typically, the following error means that the access token used to make the call was generated using API credentials that have insufficient permissions. This API can be called using the Manage Users or Manage All scope only.

{
    "status": {
        "error": true,
        "code": 401,
        "type": "Unauthorized",
        "message": "Insufficient Permission"
    }
}

Response Elements

expires_at

Date and time at which the session token will expire. Tokens expire two minutes after creation.

return_to_url

Returns the return_to_url value sent in the request, if applicable.

session_token

Provides the session token that can be used to log the user in.

In cases in which you are using this API to simply delegate authentication, you can treat this token as a confirmation that the user has been authenticated.

status

Authenticated: Indicates that the username_or_email and password values sent in the request are valid.

user

Provides information about the user that will be logged in via the session token.

  • email
  • firstname
  • id
  • lastname
  • username

Postman Collection

Replace sample variables indicated by < > in the sample request body with your actual values. Also, be sure to set Postman-specific environment variables indicated by {{ }}.

Download for the Users API

Sample cURL Request

Replace sample values indicated by < > with your actual values.

curl 'https://api.<us_or_eu>.onelogin.com/api/1/login/verify_factor' \
-X POST \
-H "Authorization: bearer:<access_token>" \
-H "Content-Type: application/json" \
-d '{
    "otp_token": "<otp_token>",
    "device_id": "<device_id>",
    "state_token": "<state_token>"
}'

Have a Question?

Have a how-to question? Seeing a weird error? Ask us about it on StackOverflow.

Found a bug? Submit a support ticket.

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