Home >
API >
1 >
SAML Assertions >
Verify Factor

Verify Factor

Deprecated

This version is deprecated and will be removed in February 2021.

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.

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

Resource URL

Before calling this API, consider using its version /2 equivalent.

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

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

Sample Response

200 OK
400 Bad Request
401 Unauthorized
404 Not Found

{
    "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 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 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

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/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?

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.