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-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 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": "2022-08-25T00:31:00.000Z",
    • "factorType": "call",
    • "id": "caf8m6jbcvUH8mAep1d7",
    • "lastUpdated": "2022-08-25T00:31:00.000Z",
    • "profile": { },
    • "provider": "string",
    • "status": "ACTIVE",
    • "vendorName": "OKTA",
    • "_embedded": {
      },
    • "_links": { }
    }
]

Enroll a Factor
OAuth 2.0: okta.users.manage

Enrolls a supported Factor for the specified user. Some Factor types require a seperate activation to complete the enrollment process. See Activate a Factor.

Request
path Parameters
userId
required
string

ID of an existing Okta user

query Parameters
updatePhone
boolean
Default: false

If true, indicates 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. 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 sms Factor is immediately activated as part of the enrollment. An activation text message isn't sent to the device.

header Parameters
Accept-Language
string

An ISO 639-1 two-letter language code that defines a localized message to send. 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. You should format phone numbers to use the E.164 standard.

provider
string

Provider for the Factor

Value: "OKTA"
_links
object
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": 1234,
    • "phoneNumber": "+15554151337"
    },
  • "provider": "OKTA",
  • "_links": { }
}
Response samples
application/json
{
  • "created": "2022-08-25T00:31:00.000Z",
  • "factorType": "call",
  • "id": "caf8m6jbcvUH8mAep1d7",
  • "lastUpdated": "2022-08-25T00:31:00.000Z",
  • "profile": {
    • "phoneExtension": 1234,
    • "phoneNumber": "+15554151337"
    },
  • "provider": "OKTA",
  • "status": "ACTIVE",
  • "vendorName": "OKTA",
  • "_embedded": {
    • "property1": { },
    • "property2": { }
    },
  • "_links": { }
}

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
[
  • {
    • "enrollment": "OPTIONAL",
    • "factorType": "call",
    • "provider": "CUSTOM",
    • "status": "ACTIVE",
    • "vendorName": "OKTA",
    • "_embedded": {
      },
    • "_links": {
      }
    }
]

List all supported Security Questions

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": "2022-08-25T00:31:00.000Z",
  • "factorType": "call",
  • "id": "caf8m6jbcvUH8mAep1d7",
  • "lastUpdated": "2022-08-25T00:31:00.000Z",
  • "profile": {
    • "phoneExtension": 1234,
    • "phoneNumber": "+15554151337"
    },
  • "provider": "OKTA",
  • "status": "ACTIVE",
  • "vendorName": "OKTA",
  • "_embedded": {
    • "property1": { },
    • "property2": { }
    },
  • "_links": { }
}

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

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
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": 1234567890
}
Response samples
application/json
{
  • "created": "2022-08-25T00:31:00.000Z",
  • "factorType": "call",
  • "id": "caf8m6jbcvUH8mAep1d7",
  • "lastUpdated": "2022-08-25T00:31:00.000Z",
  • "profile": {
    • "phoneExtension": 1234,
    • "phoneNumber": "+15554151337"
    },
  • "provider": "OKTA",
  • "status": "ACTIVE",
  • "vendorName": "OKTA",
  • "_embedded": {
    • "property1": { },
    • "property2": { }
    },
  • "_links": { }
}

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

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

Provider for the Factor

Value: "OKTA"
_links
object
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": 1234,
    • "phoneNumber": "+15554151337"
    },
  • "provider": "OKTA",
  • "_links": { }
}
Response samples
application/json
{
  • "created": "2022-08-25T00:31:00.000Z",
  • "factorType": "call",
  • "id": "caf8m6jbcvUH8mAep1d7",
  • "lastUpdated": "2022-08-25T00:31:00.000Z",
  • "profile": {
    • "phoneExtension": 1234,
    • "phoneNumber": "+15554151337"
    },
  • "provider": "OKTA",
  • "status": "ACTIVE",
  • "vendorName": "OKTA",
  • "_embedded": {
    • "property1": { },
    • "property2": { }
    },
  • "_links": { }
}

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
{
  • "factorResult": "WAITING",
  • "profile": {
    • "credentialId": "dade.murphy@example.com"
    },
  • "_links": {
    • "poll": {
      },
    • "cancel": {
      }
    }
}

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: 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. Required to verify push Factors.

Accept-Language
string

An ISO 639-1 two-letter language code that defines a localized message to send. 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

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.

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": 1234567890
}
Response samples
application/json
{
  • "expiresAt": "2022-08-25T00:31:00.000Z",
  • "factorMessage": "string",
  • "factorResult": "CHALLENGE",
  • "_embedded": {
    • "property1": { },
    • "property2": { }
    },
  • "_links": {
    • "activate": {
      },
    • "cancel": {
      },
    • "deactivate": {
      },
    • "enroll": {
      },
    • "factor": {
      },
    • "poll": {
      },
    • "qrcode": {
      },
    • "question": {
      },
    • "resend": {
      },
    • "send": {
      },
    • "self": {
      },
    • "user": {
      },
    • "verify": {
      }
    }
}