Home >
API >
1 >
Login Pages >
Verify Factor

Verify Factor

Verify a one-time password (OTP) value, provided for a second factor, when multi-factor authentication (MFA) is required.

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

If a user’s device has OneLogin Protect, the Verify call triggers a push notification.

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://<subdomain>/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.

Custom-Allowed-Origin-Header-1

string

Required for CORS requests only. Set to the Origin URI from which you are allowed to send a request using CORS.

<protocol>://<hostname>:<port>

Port is optional. Do not include path information. Add as many comma-delimited URIs as you like, limited only by header length. You can use additional headers if needed.

For example,

https://www.foo.com,https://doggerel.com:4567

You can use as many headers as you want.

For more information, see Logging a User in Via API and Create Session Via API Token.

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 or Yubikey, which immediately provide an OTP value to the user; the otp_token value is required as it is immediately available to the user

do_not_notify

boolean

When verifying MFA via Protect Push, set this to true to stop additional push notifications being sent to the OneLogin Protect device.

e.g. You would make the first request with this set to false to trigger a notification on the users device requesting MFA. You would then make subsequent requests to this API with this value set to true while polling for the users approve/deny response.

Sample Request Body

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

Sample Response

200 OK
400 Bad Request
401 Unauthorized

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

Clicking Run in Postman button navigates to the page where you can fork the collection to your workspace. Forking the collection into your workspace will enable you to contribute to the source collection using pull requests. You can also view the collection in a public workspace if you like and even import a copy of the collection using the links present on the screen.

Sample cURL Request

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

curl 'https://<subdomain>/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?

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.