User Factors

The Factors API provides operations to enroll, manage, and verify factors for multifactor authentication (MFA). Generally, authentication involves verifying a different one-time passcode (OTP). Manage both administration and end-user accounts, or verify an individual factor at any time. Okta supports several different types of factors:

Factor Type Description
call Software OTP sent using a voice call to a registered phone number
sms Software OTP sent using SMS to a registered phone number
email Software OTP sent using email
question Additional knowledge-based security question
push Out-of-band verification using a push notification to a device and transaction verification with digital signature
token Software or hardware OTP sent to a device
token:hardware Hardware OTP sent to a device
token:hotp Custom TOTP factor that uses an extension of the HMAC (Hash-Based Message Authentication Codes)-based one-time passcode (HOTP) algorithm
token:software:totp Software time-based one-time passcode (TOTP)
u2f Hardware Universal 2nd Factor (U2F) device
web HTML inline frame (iframe) for embedding verification from a third party
webauthn Hardware WebAuthn device
signed_nonce Okta Fastpass (device-bound authentication). This is available for OIE orgs if the org has users that have enrolled with Okta Verify after the org started using OIE.

List all YubiKey OTP tokens
OAuth 2.0:
  • okta.users.read

Lists all YubiKey OTP tokens

Request
query Parameters
after
string

Specifies the pagination cursor for the next page of tokens

expand
string

Embeds the user resource if the YubiKey token is assigned to a user and expand is set to user

filter
string

The expression used to filter tokens

Enum: "profile.email" "profile.serial" "activated" "user.id" "created" "status" "lastVerified"
forDownload
boolean
Default: false

Returns tokens in a CSV to download instead of in the response. When you use this query parameter, the limit default changes to 1000.

limit
integer <= 200
Default: 20

Specifies the number of results per page

sortBy
string

The value of how the tokens are sorted

Enum: "profile.email" "profile.serial" "activated" "user.id" "created" "status" "lastVerified"
sortOrder
string

Specifies the sort order, either ASC or DESC

Enum: "ASC" "DESC"
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/org/factors/yubikey_token/tokens
Request samples 
Response samples 
application/json
[]
Upload a YubiKey OTP seed
OAuth 2.0: 
  • okta.users.manage
Uploads a seed for a user to enroll a YubiKey OTP


Request 
query Parameters
after
string
Specifies the pagination cursor for the next page of tokens


 
expand
string
Embeds the user resource if the YubiKey token is assigned to a user and expand is set to user


 
filter
string
The expression used to filter tokens


 Enum: "profile.email" "profile.serial" "activated" "user.id" "created" "status" "lastVerified"  
forDownload
boolean
 Default:  false
Returns tokens in a CSV to download instead of in the response. When you use this query parameter, the limit default changes to 1000.


 
limit
integer  <= 200 
 Default:  20
Specifies the number of results per page


 
sortBy
string
The value of how the tokens are sorted


 Enum: "profile.email" "profile.serial" "activated" "user.id" "created" "status" "lastVerified"  
sortOrder
string
Specifies the sort order, either ASC or DESC


 Enum: "ASC" "DESC"  
Request Body schema: application/json
required
serialNumber
string
The unique identifier assigned to each YubiKey device


 
publicId
string
The YubiKey's public ID


 
privateId
string
The YubiKey's private ID


 
aesKey
string
The cryptographic key used in the AES (Advanced Encryption Standard) algorithm to encrypt and decrypt the YubiKey OTP


 
Responses 
200
Success


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/org/factors/yubikey_token/tokens
Request samples 
application/json
{
  • "serialNumber": "7886622",
  • "publicId": "ccccccijgibu",
  • "privateId": "b74be6169486",
  • "aesKey": "1fcc6d8ce39bf1604e0b17f3e0a11067"
}
Response samples 
application/json
{}
Retrieve a YubiKey OTP token
OAuth 2.0: 
  • okta.users.read
Retrieves the specified YubiKey OTP token by id


Request 
path Parameters
tokenId
required
string
The YubiKey OTP token ID


 
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/org/factors/yubikey_token/tokens/{tokenId}
Request samples 
Response samples 
application/json
{}
List all enrolled factors
OAuth 2.0: 
  • okta.users.read
Lists all enrolled factors for the specified user


Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
 Example:  00ub0oNGTSWTBKOLGLNR
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/users/{userId}/factors
Request samples 
Response samples 
application/json
[]
Enroll a factor
OAuth 2.0: 
  • okta.users.manage
Enrolls a supported factor for the specified user




Note: All responses return the enrolled factor with a status of either PENDING_ACTIVATION or ACTIVE.




Additional SMS/Call factor information


    

  • Rate limits: Okta may return a 429 Too Many Requests status code if you attempt to resend an SMS or a voice call challenge (OTP) within the same time window. The current rate limit is one SMS/CALL challenge per phone number every 30 seconds.
    

    • 

  • Existing phone numbers: Okta may return a 400 Bad Request status code if a user attempts to enroll with a different phone number when the user has an existing mobile phone or has an existing phone with voice call capability. A user can enroll only one mobile phone for sms and enroll only one voice call capable phone for call factor.
    

    • 



Additional WebAuthn factor information


    

  • For detailed information on the WebAuthn standard, including an up-to-date list of supported browsers, see webauthn.me.
    

    • 

  • When you enroll a WebAuthn factor, the activation object in _embedded contains properties used to help the client to create a new WebAuthn credential for use with Okta. See the WebAuthn spec for PublicKeyCredentialCreationOptions.
    

    • 



Additional Custom TOTP factor information


    

  • The enrollment process involves passing both the factorProfileId and sharedSecret properties for a token.
    

    • 

  • A factor profile represents a particular configuration of the Custom TOTP factor. It includes certain properties that match the hardware token that end users possess, such as the HMAC algorithm, passcode length, and time interval. There can be multiple Custom TOTP factor profiles per org, but users can only enroll in one Custom TOTP factor. Admins can create Custom TOTP factor profiles in the Admin Console. Then, copy the factorProfileId from the Admin Console into the API request.
    

    • 

  • 
For Custom TOTP enrollment, Okta automaticaly enrolls a user with a token:software:totp factor and the push factor if the user isn't currently enrolled with these factors.
    

    • 



Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
 Example:  00ub0oNGTSWTBKOLGLNR
query Parameters
updatePhone
boolean
 Default:  false
If true, indicates that you are replacing the currently registered phone number for the specified user. This parameter is ignored if the existing phone number is used by an activated factor.


 
templateId
string
ID of an existing custom SMS template. See the SMS Templates API. This parameter is only used by sms factors. If the provided ID doesn't exist, the default template is used instead.


 
 Example:  templateId=cstk2flOtuCMDJK4b0g3
tokenLifetimeSeconds
integer <int32>   [ 1 .. 86400 ] 
 Default:  300
Defines how long the token remains valid


 
activate
boolean
 Default:  false
If true, the factor is immediately activated as part of the enrollment. An activation process isn't required. Currently auto-activation is supported by sms, call, email and token:hotp (Custom TOTP) factors.


 
header Parameters
Accept-Language
string
An ISO 639-1 two-letter language code that defines a localized message to send. This parameter is only used by sms factors. If a localized message doesn't exist or the templateId is incorrect, the default template is used instead.


 
 Example:  fr
Request Body schema: application/json
required
Factor


factorType
string
Type of factor


 
object
Specific attributes related to the factor


 
phoneExtension
string or null  <= 15 characters 
Extension of the associated phoneNumber


 
phoneNumber
string  <= 15 characters ^\+[1-9]\d{1,14}$
Phone number of the factor. Format phone numbers to use the E.164 standard.


 
provider
string
Provider for the factor. Each provider can support a subset of factor types.


 Value: "OKTA"  
Responses 
200
Success


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/users/{userId}/factors
Request samples 
application/json
{
  • "question": {
    • "summary": "question factor",
    • "value": {
      }
    }
}
Response samples 
application/json
{}
List all supported factors
OAuth 2.0: 
  • okta.users.read
Lists all the supported factors that can be enrolled for the specified user


Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
 Example:  00ub0oNGTSWTBKOLGLNR
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/users/{userId}/factors/catalog
Request samples 
Response samples 
application/json
[]
List all supported security questions
CORS
Lists all available security questions for the specified user


Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
 Example:  00ub0oNGTSWTBKOLGLNR
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/users/{userId}/factors/questions
Request samples 
Response samples 
application/json
[
  • {
    • "question": "disliked_food",
    • "questionText": "What is the food you least liked as a child?"
    },
  • {
    • "question": "name_of_first_plush_toy",
    • "questionText": "What is the name of your first stuffed animal?"
    },
  • {
    • "question": "first_award",
    • "questionText": "What did you earn your first medal or award for?"
    }
]
Retrieve a factor
OAuth 2.0: 
  • okta.users.read
Retrieves an existing factor for the specified user


Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
 Example:  00ub0oNGTSWTBKOLGLNR
factorId
required
string
ID of an existing user factor


 
 Example:  zAgrsaBe0wVGRugDYtdv
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/users/{userId}/factors/{factorId}
Request samples 
Response samples 
application/json
{}
Unenroll a factor
OAuth 2.0: 
  • okta.users.manage
Unenrolls an existing factor for the specified user. You can't unenroll a factor from a deactivated user. Unenrolling a factor allows the user to enroll a new factor.




Note: If you unenroll the push or the signed_nonce factors, Okta also unenrolls any other totp, signed_nonce, or Okta Verify push factors associated with the user.




Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
 Example:  00ub0oNGTSWTBKOLGLNR
factorId
required
string
ID of an existing user factor


 
 Example:  zAgrsaBe0wVGRugDYtdv
query Parameters
removeRecoveryEnrollment
boolean
 Default:  false
If true, removes the phone number as both a recovery method and a factor. This parameter is only used for the sms and call factors.


 
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


delete/api/v1/users/{userId}/factors/{factorId}
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}
Activate a factor
OAuth 2.0: 
  • okta.users.manage
Activates a factor. Some factors (call, email, push, sms, token:software:totp, u2f, and webauthn) require activation to complete the enrollment process.


Okta enforces a rate limit of five activation attempts within five minutes. After a user exceeds the rate limit, Okta returns an error message.




Note: If the user exceeds their SMS, call, or email factor activation rate limit, then an OTP resend request isn't allowed for the same factor.




Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
 Example:  00ub0oNGTSWTBKOLGLNR
factorId
required
string
ID of an existing user factor


 
 Example:  zAgrsaBe0wVGRugDYtdv
Request Body schema: application/json
optional
One of:
Attempts to activate a call factor with the specified passcode


passCode
string (UserFactorPassCode) 
OTP for the current time window


 
Responses 
200
Success


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/users/{userId}/factors/{factorId}/lifecycle/activate
Request samples 
application/json
{
  • "passCode": "123456"
}
Response samples 
application/json
{}
Resend a factor enrollment
OAuth 2.0: 
  • okta.users.manage
Resends an sms, call, or email factor challenge as part of an enrollment flow.


For call and sms factors, Okta enforces a rate limit of one OTP challenge per device every 30 seconds. You can configure your sms and call factors to use a third-party telephony provider. See the Telephony inline hook reference. Okta alternates between SMS providers with every resend request to ensure delivery of SMS and Call OTPs across different carriers.




Note: Resend operations aren't allowed after a factor exceeds the activation rate limit. See Activate a factor.




Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
 Example:  00ub0oNGTSWTBKOLGLNR
factorId
required
string
ID of an existing user factor


 
 Example:  zAgrsaBe0wVGRugDYtdv
query Parameters
templateId
string
ID of an existing custom SMS template. See the SMS Templates API. This parameter is only used by sms factors.


 
 Example:  templateId=cstk2flOtuCMDJK4b0g3
Request Body schema: application/json
required
factorType
string
Type of factor


 
object
Specific attributes related to the factor


 
phoneExtension
string or null  <= 15 characters 
Extension of the associated phoneNumber


 
phoneNumber
string  <= 15 characters ^\+[1-9]\d{1,14}$
Phone number of the factor. Format phone numbers to use the E.164 standard.


 
provider
string
Provider for the factor. Each provider can support a subset of factor types.


 Value: "OKTA"  
Responses 
200
Success


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/users/{userId}/factors/{factorId}/resend
Request samples 
application/json
{
  • "factorType": "sms",
  • "provider": "OKTA",
  • "profile": {
    • "phoneNumber": "+1-555-415-1337"
    }
}
Response samples 
application/json
{}
Retrieve a factor transaction status
OAuth 2.0: 
  • okta.users.read
Retrieves the status of a push factor verification transaction




 Note:
When you have Number Matching Challenge For Factors API enabled as an Early Access Self-Service feature, you can send number matching push challenges to Okta Verify push factor enrollments.
Use Verify a factor to send a number matching push challenge.
Enable the feature for your org from the Settings > Features page in the Admin Console.




Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
 Example:  00ub0oNGTSWTBKOLGLNR
factorId
required
string
ID of an existing user factor


 
 Example:  zAgrsaBe0wVGRugDYtdv
transactionId
required
string
ID of an existing factor verification transaction


 
 Example:  gPAQcN3NDjSGOCAeG2Jv
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/users/{userId}/factors/{factorId}/transactions/{transactionId}
Request samples 
Response samples 
application/json
{}
Verify a factor
OAuth 2.0: 
  • okta.users.manage
Verifies an OTP for a factor. Some factors (call, email, push, sms, u2f, and webauthn) must first issue a challenge before you can verify the factor. Do this by making a request without a body. After a challenge is issued, make another request to verify the factor.




 Note:
When you have Number Matching Challenge For Factors API enabled as an Early Access Self-Service feature, you can send number matching push challenges to Okta Verify push factor enrollments.
Enable the feature for your org from the Settings > Features page in the Admin Console.






Note: To verify a push factor, use the poll link returned when you issue the challenge. See Retrieve a factor transaction status.




Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
 Example:  00ub0oNGTSWTBKOLGLNR
factorId
required
string
ID of an existing user factor


 
 Example:  zAgrsaBe0wVGRugDYtdv
query Parameters
templateId
string
ID of an existing custom SMS template. See the SMS Templates API. This parameter is only used by sms factors.


 
 Example:  templateId=cstk2flOtuCMDJK4b0g3
tokenLifetimeSeconds
integer <int32>   [ 1 .. 86400 ] 
 Default:  300
Defines how long the token remains valid


 
header Parameters
X-Forwarded-For
string
Public IP address for the user agent


 
User-Agent
string
Type of user agent detected when the request is made. Required to verify push factors.


 
Accept-Language
string
An ISO 639-1 two-letter language code that defines a localized message to send. This parameter is only used by sms factors. If a localized message doesn't exist or the templateId is incorrect, the default template is used instead.


 
 Example:  fr
Request Body schema: application/json
optional
Verifies an OTP for a factor. Some factors (call, email, push, sms, u2f, and webauthn) must first issue a challenge before you can verify the factor. Do this by making a request without a body. After a challenge is issued, make another request to verify the factor.




 Note:
Unlike other challenges which use a request without a body, a number matching push challenge requires a request body. useNumberMatchingChallenge must be set to true.
When a number matching challenge is issued for an Okta Verify push factor enrollment, a correctAnswer challenge object is returned in the _embedded object.




One of:
Verifies an OTP sent by a call factor challenge. If you omit passCode in the request, a new OTP is sent to the phone.


passCode
string (UserFactorPassCode) 
OTP for the current time window


 
Responses 
200
Success


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/users/{userId}/factors/{factorId}/verify
Request samples 
application/json
{
  • "passCode": "123456"
}
Response samples 
application/json
{
  • "factorResult": "SUCCESS"
}