See api-docs Menu

Activate an Authentication Factor


Use this API to trigger an SMS or Push notification containing a One-Time Password (OTP) that can be used to authenticate a user with the Verify Factor call.

It is only necessary to activate a factor if needs_trigger is returned as true via the Enroll Factor or Get Enrolled Factors calls.

Resource URL

https://<subdomain>/api/1/users/<user_id>/otp_devices/<device_id>/trigger

Header Parameter

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 one of the following scopes: Manage users or Manage All.

Resource Parameters

user_id

required

integer

Set to the id of the user.

If you don’t know the user’s id, use the Get Users API call to return all users and their id values.

device_id

required

integer

Set to the device_id of the MFA device.

The device_id is returned on enrollment of a factor or you can get the device_id using the Get Enrolled Factors API call.

Request Parameter

state_token_expires_in

integer

Optional. Sets the window of time in seconds that the factor must be verified within.

Defaults to 120 seconds (2 minutes). Max 900 seconds (15 minutes).

numeric_sms_otp

boolean

Optional. Defaults to false. Only applies to SMS factor.

When set to `true` a 6 digit numeric code will be sent to the user instead of the standard code which is alphanumeric.

sms_message

string

Optional. Only applies to SMS factor.

A message template that will be sent via SMS. Max length of the message after template items are inserted is 160 characters.

The following template variables can be included in the message.

  • {{otp_code}} - The security code.
  • {{expiration}} - The number of minutes until the one time code expires.

Request Body

With optional state token expiry

{
  "state_token_expires_in": 300
}

With optional sms options

{
  "numeric_sms_otp": true,
  "sms_message": "This is a security code from ABC Co {{otp_code}}. It expires in {{expiration}} minutes."
}

Sample Response

{
    "status": {
        "type": "success",
        "code": 200,
        "message": "SMS token sent to your mobile device. Authentication pending.",
        "error": false
    },
    "data": [
        {
            "user_display_name": "Rich's Phone",
            "active": false,
            "state_token": "98e008497066bc2763c52342996e06358aab2e32",
            "state_token_expires_at": "2019-10-25T16:29:42Z",
            "auth_factor_name": "OneLogin SMS",
            "type_display_name": "OneLogin SMS",
            "id": 35510511,
            "device_id": 525509
        }
    ]
}
{
    "status": {
        "error": true,
        "code": 400,
        "type": "bad request",
        "message": "Authorization Information is incorrect"
    }
}
{
    "status": {
        "type": "bad request",
        "code": 400,
        "message": "User does not exist",
        "error": true
    }
}
{
    "status": {
        "type": "bad request",
        "code": 400,
        "message": "Factor could not be found",
        "error": true
    }
}
{
    "status": {
        "error": true,
        "code": 401,
        "type": "Unauthorized",
        "message": "Authentication Failure"
    }
}

Response Elements

user_display_name Authentication factor display name assigned by users when they register the device.

active

true = enabled (used successfully for authentication at least once). false = pending (registered but never used).

state_token A short lived token that is required to Verify the Factor.
state_token_expires_at ISO8601 timestamp that indicates when the state token expires. Default expiry is 120 seconds (2 minutes).
auth_factor_name "Official" authentication factor name, as it appears to administrators in OneLogin.
type_display_name Authentication factor display name as it appears to users upon initial registration, as defined by admins at Settings > Authentication Factors.
id User identifier
device_id MFA device identifier.

Postman Collection

Replace sample variables indicated by {{ }} with your actual values.

Download for the MFA API

Sample Code

cURL

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

curl 'https://<subdomain>/api/1/users/<user_id>/otp_devices/<device_id>/trigger' \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: bearer: <access_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.