Home >
API >
1 >
Multi-Factor Auth >
Activate an Authentication Factor

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

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

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

200 OK
400 Bad Request
401 Unauthorized

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

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

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.