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

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

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

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

200 OK
400 Bad Request
401 Unauthorized

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

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' \
-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.