Home >
API >
2 >
SAML Assertions >
Verify Factor

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.

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

Resource URL

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

{
    "data": "PHNhbWxwOlJlc3BvbnNlIHhtbG5zOnNhbWw9InVybjpvYXNpczpuYW1lczp0YzpTQU1MOjIuMDphc3NlcnRpb24iIHhtbG5zOnNhbWxwPSJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6cHJvdG9jb2wiIElEPSJSZjE5Y2EyMTI0ZGMxNzJmNzhmMjI3OTk3YzMwOTBkODVkNzFjYWMzOCIgVmVyc2lvbj0iMi4wIiBJc3N1ZUluc3RhbnQ9IjIwMjAtM...",
    "message": "Success"
}

{
    "message": "SMS token sent to your mobile device. Authentication pending."
}

{
    "message": "State token is invalid or expired",
    "statusCode": 400,
    "name": "Bad Request"
}

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

{
    "message": "Factor could not be found",
    "statusCode": 400,
    "name": "Bad Request"
}

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

{
    "message": "Authorization Information is incorrect",
    "statusCode": 400,
    "name": "Bad Request"
}

{
    "message": "Content-Type is not specified or specified incorrectly.
                Content-Type header must be set to application/json",
    "statusCode": 400,
    "name": "Bad Request"
}

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

{
    "message": "Failed authentication with this factor",
    "statusCode": 401,
    "name": "Unauthorized"
}

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

{
    "message": "Authentication Failure",
    "statusCode": 401,
    "name": "Unauthorized"
}

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.

{
    "message": "Insufficient Permission",
    "statusCode": 401,
    "name": "Unauthorized"
}

{
    "message": "App could not be found",
    "statusCode": 404,
    "name": "Not found"
}

Response Elements

`data`	Provides the SAML assertion.
`message`	Plain text description describing the outcome of the response.

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/2/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.