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. |
okta.users.read
Lists all YubiKey OTP Tokens
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 |
filter | string The expression used to filter tokens |
forDownload | boolean Default: false Returns tokens in a CSV to download instead of in the response. When you use this query parameter, the |
limit | integer <= 200 Default: 20 Specifies the number of results per page |
sortBy | string The value of how the tokens are sorted |
sortOrder | string Specifies the sort order, either |
Success
Forbidden
Not Found
Too Many Requests
[- {
- "id": "ykkwcx13nrDq8g4oy0g3",
- "created": "2020-01-14T21:53:09.000Z",
- "lastVerified": "2020-01-14T21:53:06.000Z",
- "lastUpdated": "2020-01-14T21:53:09.000Z",
- "status": "UNASSIGNED",
- "profile": {
- "serial": "000003632071"
}, - "_links": {
- "self": {
- "hints": {
- "allow": [
- "GET",
- "DELETE"
]
}
}
}
}, - {
- "id": "ykkxdtCA1fKVxyu6R0g3",
- "created": "2020-06-09T23:42:05.000Z",
- "activated": "2020-06-09T23:47:29.000Z",
- "lastVerified": "2020-06-09T23:47:29.000Z",
- "lastUpdated": "2020-06-09T23:47:29.000Z",
- "status": "ACTIVE",
- "profile": {
- "serial": "000009508427"
}, - "_links": {
- "self": {
- "hints": {
- "allow": [
- "GET"
]
}
}, - "user": {
- "hints": {
- "allow": [
- "GET"
]
}
}, - "deactivate": {
- "hints": {
- "allow": [
- "DELETE"
]
}
}
}
}
]
okta.users.manage
Uploads a seed for a user to enroll a YubiKey OTP
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 |
filter | string The expression used to filter tokens |
forDownload | boolean Default: false Returns tokens in a CSV to download instead of in the response. When you use this query parameter, the |
limit | integer <= 200 Default: 20 Specifies the number of results per page |
sortBy | string The value of how the tokens are sorted |
sortOrder | string Specifies the sort order, either |
Success
Bad Request
Forbidden
Not Found
Too Many Requests
{- "serialNumber": "7886622",
- "publicId": "ccccccijgibu",
- "privateId": "b74be6169486",
- "aesKey": "1fcc6d8ce39bf1604e0b17f3e0a11067"
}
{- "id": "ykkut4G6ti62DD8Dy0g3",
- "created": "2020-01-10T23:04:10.000Z",
- "lastVerified": "2020-01-10T23:04:10.000Z",
- "lastUpdated": "2020-01-10T23:04:10.000Z",
- "status": "UNASSIGNED",
- "profile": {
- "serial": "000007886622"
}, - "_links": {
- "self": {
- "hints": {
- "allow": [
- "GET",
- "DELETE"
]
}
}
}
}
okta.users.read
Retrieves the specified YubiKey OTP Token by id
Success
Forbidden
Not Found
Too Many Requests
{- "id": "ykkxdtCA1fKVxyu6R0g3",
- "created": "2020-06-09T23:42:05.000Z",
- "activated": "2020-06-09T23:47:29.000Z",
- "lastVerified": "2020-06-09T23:47:29.000Z",
- "lastUpdated": "2020-06-09T23:47:29.000Z",
- "status": "ACTIVE",
- "profile": {
- "serial": "000009508427"
}, - "_links": {
- "self": {
- "hints": {
- "allow": [
- "GET"
]
}
}, - "user": {
- "hints": {
- "allow": [
- "GET"
]
}
}, - "deactivate": {
- "hints": {
- "allow": [
- "DELETE"
]
}
}
}
}
okta.users.read
Lists all enrolled Factors for the specified user
Success
Forbidden
Not Found
Too Many Requests
[- {
- "id": "ufs2bysphxKODSZKWVCT",
- "factorType": "question",
- "provider": "OKTA",
- "vendorName": "OKTA",
- "status": "ACTIVE",
- "created": "2014-04-15T18:10:06.000Z",
- "lastUpdated": "2014-04-15T18:10:06.000Z",
- "profile": {
- "question": "favorite_art_piece",
- "questionText": "What is your favorite piece of art?"
}, - "_links": {
- "questions": {
- "hints": {
- "allow": [
- "GET"
]
}
}, - "self": {
- "hints": {
- "allow": [
- "GET",
- "DELETE"
]
}
}, - "user": {
- "hints": {
- "allow": [
- "GET"
]
}
}
}
}, - {
- "id": "ostf2gsyictRQDSGTDZE",
- "factorType": "token:software:totp",
- "provider": "OKTA",
- "status": "PENDING_ACTIVATION",
- "created": "2014-06-27T20:27:33.000Z",
- "lastUpdated": "2014-06-27T20:27:33.000Z",
- "profile": {
- "credentialId": "dade.murphy@example.com"
}, - "_links": {
- "next": {
- "name": "activate",
- "hints": {
- "allow": [
- "POST"
]
}
}, - "self": {
- "hints": {
- "allow": [
- "GET"
]
}
}, - "user": {
- "hints": {
- "allow": [
- "GET"
]
}
}
}, - "_embedded": {
- "activation": {
- "timeStep": 30,
- "sharedSecret": "HE64TMLL2IUZW2ZLB",
- "encoding": "base32",
- "keyLength": 16
}
}
}, - {
- "id": "sms2gt8gzgEBPUWBIFHN",
- "factorType": "sms",
- "provider": "OKTA",
- "status": "ACTIVE",
- "created": "2014-06-27T20:27:26.000Z",
- "lastUpdated": "2014-06-27T20:27:26.000Z",
- "profile": {
- "phoneNumber": "+1-555-415-1337"
}, - "_links": {
- "verify": {
- "hints": {
- "allow": [
- "POST"
]
}
}, - "self": {
- "hints": {
- "allow": [
- "GET",
- "DELETE"
]
}
}, - "user": {
- "hints": {
- "allow": [
- "GET"
]
}
}
}
}
]
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`.
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.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.Enroll WebAuthn response parameters
For detailed information on the Webauthn standard, including an up-to-date list of supported browsers, see webauthn.me.
In the enroll API response, the response._embedded.activation
object contains properties used to help the client to create a new WebAuthn credential for use with Okta. See the WebAuthn spec for PublicKeyCredentialCreationOptions.
Enroll Custom TOTP Factor
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.
token:software:totp
factor and the push
factor if the user isn't currently enrolled with these factors.
updatePhone | boolean Default: false If |
templateId | string ID of an existing custom SMS template. See the SMS Templates API. This parameter is only used by Example: templateId=cstk2flOtuCMDJK4b0g3 |
tokenLifetimeSeconds | integer <int32> [ 1 .. 86400 ] Default: 300 Defines how long the token remains valid |
activate | boolean Default: false If |
Factor
factorType | string Type of Factor | ||||
object Specific attributes related to the Factor | |||||
| |||||
provider | string Provider for the Factor |
Success
Bad Request
Forbidden
Not Found
Too Many Requests
{- "question": {
- "summary": "question factor",
- "value": {
- "factorType": "question",
- "provider": "OKTA",
- "profile": {
- "question": "disliked_food",
- "answer": "mayonnaise"
}
}
}
}
{- "id": "ufs1o01OTMGHLAJPVHDZ",
- "factorType": "question",
- "provider": "OKTA",
- "vendorName": "OKTA",
- "status": "ACTIVE",
- "created": "2014-08-05T22:58:49.000Z",
- "lastUpdated": "2014-08-05T22:58:49.000Z",
- "profile": {
- "question": "disliked_food",
- "questionText": "What is the food you least liked as a child?"
}, - "_links": {
- "questions": {
- "hints": {
- "allow": [
- "GET"
]
}
}, - "self": {
- "hints": {
- "allow": [
- "GET",
- "DELETE"
]
}
}, - "user": {
- "hints": {
- "allow": [
- "GET"
]
}
}
}
}
okta.users.read
Lists all the supported Factors that can be enrolled for the specified user
Success
Forbidden
Not Found
Too Many Requests
[- {
- "factorType": "question",
- "provider": "OKTA",
- "vendorName": "OKTA",
- "_links": {
- "questions": {
- "hints": {
- "allow": [
- "GET"
]
}
}, - "enroll": {
- "hints": {
- "allow": [
- "POST"
]
}
}
}
}, - {
- "factorType": "token:software:totp",
- "provider": "OKTA",
- "_links": {
- "enroll": {
- "hints": {
- "allow": [
- "POST"
]
}
}
}
}, - {
- "factorType": "token:software:totp",
- "provider": "GOOGLE",
- "_links": {
- "enroll": {
- "hints": {
- "allow": [
- "POST"
]
}
}
}
}, - {
- "factorType": "sms",
- "provider": "OKTA",
- "vendorName": "OKTA",
- "_links": {
- "enroll": {
- "hints": {
- "allow": [
- "POST"
]
}
}
}, - "_embedded": {
- "phones": [
- {
- "id": "mblldntFJevYKbyQQ0g3",
- "profile": {
- "phoneNumber": "+14081234567"
}, - "status": "ACTIVE"
}
]
}
}, - {
- "factorType": "call",
- "provider": "OKTA",
- "_links": {
- "enroll": {
- "hints": {
- "allow": [
- "POST"
]
}
}
}
}, - {
- "factorType": "token",
- "provider": "RSA",
- "_links": {
- "enroll": {
- "hints": {
- "allow": [
- "POST"
]
}
}
}
}, - {
- "factorType": "token",
- "provider": "SYMANTEC",
- "_links": {
- "enroll": {
- "hints": {
- "allow": [
- "POST"
]
}
}
}
}
]
Lists all available Security Questions for the specified user
Success
Forbidden
Not Found
Too Many Requests
[- {
- "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?"
}
]
okta.users.read
Retrieves an existing Factor for the specified user
Success
Forbidden
Not Found
Too Many Requests
{- "id": "sms2gt8gzgEBPUWBIFHN",
- "factorType": "sms",
- "provider": "OKTA",
- "vendorName": "OKTA",
- "status": "ACTIVE",
- "created": "2014-06-27T20:27:26.000Z",
- "lastUpdated": "2014-06-27T20:27:26.000Z",
- "profile": {
- "phoneNumber": "+1-555-415-1337"
}, - "_links": {
- "verify": {
- "hints": {
- "allow": [
- "POST"
]
}
}, - "self": {
- "hints": {
- "allow": [
- "GET",
- "DELETE"
]
}
}, - "user": {
- "hints": {
- "allow": [
- "GET"
]
}
}
}
}
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 thesigned_nonce
Factors, Okta also unenrolls any othertotp
,signed_nonce
, or Okta Verifypush
Factors associated with the user.
No Content
Forbidden
Not Found
Too Many Requests
{- "errorCode": "E0000006",
- "errorSummary": "You do not have permission to perform the requested action",
- "errorLink": "E0000006",
- "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
- "errorCauses": [ ]
}
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 activate rate limit, then an OTP resend request (
/api/v1/users/${userId}}/factors/${factorId}/resend
) isn't allowed for the same Factor.
Success
Bad Request
Forbidden
Not Found
Too Many Requests
{- "passCode": "123456"
}
{- "id": "ostf1fmaMGJLMNGNLIVG",
- "factorType": "token:software:totp",
- "provider": "OKTA",
- "vendorName": "OKTA",
- "status": "ACTIVE",
- "created": "2014-07-16T16:13:56.000Z",
- "lastUpdated": "2014-08-06T00:31:07.000Z",
- "profile": {
- "credentialId": "dade.murphy@example.com"
}, - "_links": {
- "verify": {
- "hints": {
- "allow": [
- "POST"
]
}
}, - "self": {
- "hints": {
- "allow": [
- "GET",
- "DELETE"
]
}
}, - "user": {
- "hints": {
- "allow": [
- "GET"
]
}
}
}
}
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.
templateId | string ID of an existing custom SMS template. See the SMS Templates API. This parameter is only used by Example: templateId=cstk2flOtuCMDJK4b0g3 |
factorType | string Type of Factor | ||||
object Specific attributes related to the Factor | |||||
| |||||
provider | string Provider for the Factor |
Success
Bad Request
Forbidden
Not Found
Too Many Requests
{- "factorType": "sms",
- "provider": "OKTA",
- "profile": {
- "phoneNumber": "+1-555-415-1337"
}
}
{- "id": "mbl1nz9JHJGHWRKMTLHP",
- "factorType": "sms",
- "provider": "OKTA",
- "vendorName": "OKTA",
- "status": "PENDING_ACTIVATION",
- "created": "2014-08-05T20:59:49.000Z",
- "lastUpdated": "2014-08-06T03:59:49.000Z",
- "profile": {
- "phoneNumber": "+1-555-415-1337"
}, - "_links": {
- "activate": {
- "hints": {
- "allow": [
- "POST"
]
}
}, - "resend": [
- {
- "name": "sms",
- "hints": {
- "allow": [
- "POST"
]
}
}
], - "self": {
- "hints": {
- "allow": [
- "GET"
]
}
}, - "user": {
- "hints": {
- "allow": [
- "GET"
]
}
}
}
}
okta.users.read
Retrieves the status of a push
Factor verification transaction
Success
Forbidden
Not Found
Too Many Requests
Note: This example is abbreviated
{- "expiresAt": "2015-04-01T15:57:32.000Z",
- "factorResult": "WAITING",
- "profile": {
- "credentialId": "jane.doe@example.com"
}, - "_links": {
- "poll": {
- "hints": {
- "allow": [
- "GET"
]
}
}, - "cancel": {
- "hints": {
- "allow": [
- "DELETE"
]
}
}
}
}
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.
templateId | string ID of an existing custom SMS template. See the SMS Templates API. This parameter is only used by Example: templateId=cstk2flOtuCMDJK4b0g3 |
tokenLifetimeSeconds | integer <int32> [ 1 .. 86400 ] Default: 300 Defines how long the token remains valid |
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.
Success
Bad Request
Forbidden
Not Found
Too Many Requests
{- "value": {
- "passCode": "123456"
}
}
{- "value": {
- "factorResult": "SUCCESS"
}
}