See api-docs Menu

Verify Factor

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

This API is used in close conjunction with the Generate SAML Assertion API when MFA is required.

Resource URL

https://api.<us_or_eu>.onelogin.com/api/1/
saml_assertion/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 the Authentication Only, Manage All, and Manage Users scopes.

Content-Type

required

string

Set to application/json.

Request Parameters

app_id

required

string

App ID of the app for which you want to generate a SAML token. This is the app ID in OneLogin.

device_id

required

string

Provide the MFA device_id you are submitting for verification. The device_id is supplied by the Generate SAML Assertion 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 Generate SAML Assertion 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

{
    "app_id": "666666",
    "otp_token": "999999",
    "device_id": "111111",
    "state_token": "11x0x1x16x1x3259xxxx0x59xx6xxxx670x61x45xxxxx"
}

Sample Response

{
    "status": {
        "type": "success",
        "message": "Success",
        "code": 200,
        "error": false
    },
    "data": "PHNhbWxwOlJlc3BvbnNlIHhtbG5zOnNhbWw9InVybjpvYXNpczpuYW1lczp0YzpTQU1MOjIuMDphc
             3NlcnRpb24iIHhtbG5zOnNhbWxwPSJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6cHJvdG9jb2
             wiIElEPSJSZDkwYTY5NDg1YTdiMmMxYjM0NWFjOGQ1Y2UyZmExMzFkZmRkMzRlOSIgVmVyc2lvbj0
             iMi4wIiBJc3N1ZUluc3RhbnQ9IjIwMTYtMDMtMTdUMjI6NTA6MzBaIiBEZXN0aW5hdGlvbj0iaHR0
             cHM6Ly97c3ViZG9tYWlufS5mYWNlYm9vay5jb20vd29yay9zYW1sLnBocCI+P..."
}

{
    "status": {
        "type": "pending",
        "message": "SMS token sent to your mobile device. Authentication pending.",
        "error": false,
        "code": 200
    }
}
{
    "status": {
        "type": "bad request",
        "message": "State token is invalid or expired",
        "code": 400,
        "error": true
    }
}

Typically, the following error means that the app ID value is invalid.

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

Typically, the following error means that the Authorization header is missing or incorrectly formatted. The Authorization header should use this format: bearer:<access_token>.

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

{
    "status": {
        "error": true,
        "code": 400,
        "type": "bad request",
        "message": "Content Type is not specified or specified incorrectly. 
                    Content-Type header must be set to application/json"
    }
}

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

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

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 All scope only.

{
    "status": {
        "error": true,
        "code": 401,
        "type": "Unauthorized",
        "message": "Insufficient Permission"
    }
}
{
    "status": {
        "type": "error",
        "message": "App could not be found",
        "code": 404,
        "error": true
    }
}

Response Elements

data Provides the SAML assertion.

Postman Collection

Be sure to set Postman-specific environment variables indicated by {{ }}.

Download for the SAML Assertion API

Sample cURL Request

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

curl "https://api.<us_or_eu>.onelogin.com/api/1/saml_assertion/verify_factor" \
-X POST \
-H "Authorization: bearer:<access_token>" \
-H "Content-Type: application/json" \
-d '{
    "app_id": "<app_id>",
    "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.