See api-docs Menu

Enroll an Authentication Factor


Use this API to enroll a user with a given authentication factor.

If the authentication factor requires confirmation to complete, then the device will have an active state of false otherwise it will have an active state of true (corresponding to devices that are either pending confirmation or not)

To change the active state of the device to true, the OTP device‚Äôs id would need to be supplied to the Activate a Factor endpoint. Then the `otp_code` would need to be sent to the Verify a Factor endpoint.

Currently the API only supports enrollment of the OneLogin SMS and OneLogin Voice factors. Other factors can be enrolled manually by the user.

Resource URL

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

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 Parameter

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.

Request Parameters

factor_id

required

integer

The identifier of the factor to enroll the user with.

See Get Available Factors for a list of possible id values.

display_name

required

string

A name for the users device

number

required

string

The phone number of the user in E.164 format.

e.g. +14156456830

verified

boolean

Defaults to false. Some factors like SMS or Voice require that a user recieve a token and then that token is supplied to the Verify endpoint before the device is considered active.

You can set verfied to `true` which indicates the the users phone number is pre verified and the device can be immediately activated.

Enrollment of OneLogin Voice requires verified be set to true.

Request Body

{
  "factor_id": 16282,
  "display_name":  "Rich's Phone",
  "number": "+1xxxxxxxxxx"
}

Sample Response

{
    "status": {
        "type": "success",
        "code": 200,
        "message": "Success",
        "error": false
    },
    "data": [
        {
            "active": false,
            "default": true,
            "state_token": "f2402de2b446abd86ea5aa1f79b3fa72b4befacd",
            "auth_factor_name": "OneLogin SMS",
            "phone_number": "+1xxxxxxxxxx",
            "type_display_name": "OneLogin SMS",
            "needs_trigger": true,
            "user_display_name": "Rich's Phone",
            "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": {
        "error": true,
        "code": 401,
        "type": "Unauthorized",
        "message": "Authentication Failure"
    }
}

Response Elements

active

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

default True = is user’s default MFA device for OneLogin.
state_token A short lived token that is required to Verify the Factor. This token expires in 120 seconds.
auth_factor_name "Official" authentication factor name, as it appears to administrators in OneLogin.
phone_number

For OTP codes sent via SMS, the phone number receiving the SMS message.

type_display_name Authentication factor display name as it appears to users upon initial registration, as defined by admins at Settings > Authentication Factors.
needs_trigger

true: You MUST Activate this Factor to trigger an SMS or Push notification before Verifying the OTP code.
false: No Activation required. You can Verify the OTP immediately.

MFA factors that provide both push notifications (user accepts notification) and pull code submission (user initiates code submission from device or enters it manually) should appear twice; once with needs_trigger: true and once with needs_trigger: false.

user_display_name Authentication factor display name assigned by users when they enroll the 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' \
-X POST \
-H "Authorization: bearer: <access_token>" \
-d '{
  "factor_id": 16282,
  "display_name":  "Rich's Phone",
  "number": "+1xxxxxxxxxx"
}'

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.