User Factors

The Factors API provides operations to enroll, manage, and verify factors for multifactor authentication (MFA). Manage both administration and end-user accounts, or verify an individual factor at any time.

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

Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/users/{userId}/factors
Request samples 
Response samples 
application/json
[
  • {
    • "created": "2019-08-24T14:15:22Z",
    • "factorType": "call",
    • "id": "string",
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "profile": { },
    • "provider": "CUSTOM",
    • "status": "ACTIVE",
    • "vendorName": "OKTA",
    • "_embedded": {
      },
    • "_links": {
      }
    }
]
Enroll a Factor
OAuth 2.0: okta.users.manage
Enrolls a supported Factor for the specified user


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


 
query Parameters
updatePhone
boolean
 Default:  false
If true, indicates that you'll update the phoneNumber. Only used for sms Factors that are pending activation.


 
templateId
string
ID of an existing custom SMS template. See the SMS Templates API. Only used by sms Factors.


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


 
activate
boolean
 Default:  false
If true, the sms Factor is immediately activated as part of the enrollment. An activation text message isn't sent to the device.


 
Request Body schema: application/json
required
Factor


factorType
string (UserFactorType) 
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. You should format phone numbers to use the E.164 standard.


 
provider
string (UserFactorProvider) 
Provider for the Factor


 Enum: "CUSTOM" "DUO" "FIDO" "GOOGLE" "OKTA" "RSA" "SYMANTEC" "YUBICO"  
status
string (UserFactorStatus) 
Status of the Factor


 Enum: "ACTIVE" "DISABLED" "ENROLLED" "EXPIRED" "INACTIVE" "NOT_SETUP" "PENDING_ACTIVATION"  
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
{
  • "factorType": "call",
  • "profile": {
    • "phoneExtension": "string",
    • "phoneNumber": "+15554151337"
    },
  • "provider": "CUSTOM",
  • "status": "ACTIVE"
}
Response samples 
application/json
{
  • "created": "2019-08-24T14:15:22Z",
  • "factorType": "call",
  • "id": "string",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "profile": {
    • "phoneExtension": "string",
    • "phoneNumber": "+15554151337"
    },
  • "provider": "CUSTOM",
  • "status": "ACTIVE",
  • "vendorName": "OKTA",
  • "_embedded": {
    • "property1": { },
    • "property2": { }
    },
  • "_links": {
    • "self": {
      }
    }
}
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


 
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
[
  • {
    • "created": "2019-08-24T14:15:22Z",
    • "factorType": "call",
    • "id": "string",
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "profile": { },
    • "provider": "CUSTOM",
    • "status": "ACTIVE",
    • "vendorName": "OKTA",
    • "_embedded": {
      },
    • "_links": {
      }
    }
]
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


 
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


 
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
{
  • "created": "2019-08-24T14:15:22Z",
  • "factorType": "call",
  • "id": "string",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "profile": {
    • "phoneExtension": "string",
    • "phoneNumber": "+15554151337"
    },
  • "provider": "CUSTOM",
  • "status": "ACTIVE",
  • "vendorName": "OKTA",
  • "_embedded": {
    • "property1": { },
    • "property2": { }
    },
  • "_links": {
    • "self": {
      }
    }
}
Unenroll a Factor
OAuth 2.0: okta.users.manage
Unenrolls an existing Factor for the specified user. This 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


 
factorId
required
string
ID of an existing User Factor


 
 Example:  zAgrsaBe0wVGRugDYtdv
query Parameters
removeRecoveryEnrollment
boolean
 Default:  false
If true, removes the the phone number as both a recovery method and a Factor. Only used for 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. The sms and token:software:totp factor types 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.


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


 
factorId
required
string
ID of an existing User Factor


 
 Example:  zAgrsaBe0wVGRugDYtdv
Request Body schema: application/json
optional
attestation
string
 
clientData
string
 
passCode
string
 
registrationData
string
 
stateToken
string
 
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
{
  • "attestation": "string",
  • "clientData": "string",
  • "passCode": "string",
  • "registrationData": "string",
  • "stateToken": "string"
}
Response samples 
application/json
{
  • "created": "2019-08-24T14:15:22Z",
  • "factorType": "call",
  • "id": "string",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "profile": {
    • "phoneExtension": "string",
    • "phoneNumber": "+15554151337"
    },
  • "provider": "CUSTOM",
  • "status": "ACTIVE",
  • "vendorName": "OKTA",
  • "_embedded": {
    • "property1": { },
    • "property2": { }
    },
  • "_links": {
    • "self": {
      }
    }
}
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 round-robins between SMS providers with every resend request to help ensure delivery of an 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


 
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. Only used by sms Factors.


 
 Example:  templateId=cstk2flOtuCMDJK4b0g3
Request Body schema: application/json
required
factorType
string (UserFactorType) 
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. You should format phone numbers to use the E.164 standard.


 
provider
string (UserFactorProvider) 
Provider for the Factor


 Enum: "CUSTOM" "DUO" "FIDO" "GOOGLE" "OKTA" "RSA" "SYMANTEC" "YUBICO"  
status
string (UserFactorStatus) 
Status of the Factor


 Enum: "ACTIVE" "DISABLED" "ENROLLED" "EXPIRED" "INACTIVE" "NOT_SETUP" "PENDING_ACTIVATION"  
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": "call",
  • "profile": {
    • "phoneExtension": "string",
    • "phoneNumber": "+15554151337"
    },
  • "provider": "CUSTOM",
  • "status": "ACTIVE"
}
Response samples 
application/json
{
  • "created": "2019-08-24T14:15:22Z",
  • "factorType": "call",
  • "id": "string",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "profile": {
    • "phoneExtension": "string",
    • "phoneNumber": "+15554151337"
    },
  • "provider": "CUSTOM",
  • "status": "ACTIVE",
  • "vendorName": "OKTA",
  • "_embedded": {
    • "property1": { },
    • "property2": { }
    },
  • "_links": {
    • "self": {
      }
    }
}
Retrieve a Factor transaction status
OAuth 2.0: okta.users.read
Retrieves the status of a push Factor verification transaction


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


 
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
{
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "factorResult": "CHALLENGE",
  • "factorResultMessage": "string",
  • "_embedded": {
    • "property1": { },
    • "property2": { }
    },
  • "_links": {
    • "self": {
      }
    }
}
Verify a Factor
OAuth 2.0: okta.users.manage
Verifies an OTP for a Factor. Some Factors (call, email, push, sms, u2f, and webauthn) require Okta to issue a challenge to initiate the transaction. Do this by making a request without a body. After a challenge is issued, make another request to verify the Factor.


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


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


 
Accept-Language
string
Sets a two-letter language code that defines a localized message to send. Only used by the sms Factor.


    

  • If the language code doesn't exist in the SMS template, the message uses the default template.
    • 

  • If the templateId doesn't exist, the message is sent using the default template.
    • 



 
Request Body schema: application/json
optional
activationToken
string
 
answer
string  >= 4 characters 
Answer to the question


 
attestation
string
Base64-encoded attestation from the WebAuthn JavaScript call


 
clientData
string
Base64-encoded client data from the WebAuthn authenticator


 
nextPassCode
integer
OTP for the next time window


 
passCode
string
OTP for the current time window


 
registrationData
string
Base64-encoded registration data from the U2F JavaScript call


 
stateToken
string
 
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
{
  • "activationToken": "string",
  • "answer": "string",
  • "attestation": "string",
  • "clientData": "string",
  • "nextPassCode": 3956685498,
  • "passCode": "string",
  • "registrationData": "string",
  • "stateToken": "string"
}
Response samples 
application/json
{
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "factorResult": "CHALLENGE",
  • "factorResultMessage": "string",
  • "_embedded": {
    • "property1": { },
    • "property2": { }
    },
  • "_links": {
    • "self": {
      }
    }
}