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

[{"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": {"href": "https://{yourOktaDomain}/api/v1/org/factors/yubikey_token/tokens/ykkwcx13nrDq8g4oy0g3",
"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": {"href": "https://{yourOktaDomain}/api/v1/org/factors/yubikey_token/tokens/ykkxdtCA1fKVxyu6R0g3",
"hints": {"allow": ["GET"
]
}
},
"user": {"href": "https://{yourOktaDomain}/api/v1/users/00uu0x8sxTr9HcHOo0g3",
"hints": {"allow": ["GET"
]
}
},
"deactivate": {"href": "https://{yourOktaDomain}/api/v1/users/00uu0x8sxTr9HcHOo0g3/factors/ykfxduQAhl89YyPrV0g3",
"hints": {"allow": ["DELETE"
]
}
}
}
}
]

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

{"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": {"href": "https://{yourOktaDomain}/api/v1/org/factors/yubikey_token/tokens/ykkut4G6ti62DD8Dy0g3",
"hints": {"allow": ["GET",
"DELETE"
]
}
}
}
}

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

{"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": {"href": "https://{yourOktaDomain}/api/v1/org/factors/yubikey_token/tokens/ykkxdtCA1fKVxyu6R0g3",
"hints": {"allow": ["GET"
]
}
},
"user": {"href": "https://{yourOktaDomain}/api/v1/users/00uu0x8sxTr9HcHOo0g3",
"hints": {"allow": ["GET"
]
}
},
"deactivate": {"href": "https://{yourOktaDomain}/api/v1/users/00uu0x8sxTr9HcHOo0g3/factors/ykfxduQAhl89YyPrV0g3",
"hints": {"allow": ["DELETE"
]
}
}
}
}

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

[{"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": {"href": "https://{yourOktaDomain}/api/v1/users/00u15s1KDETTQMQYABRL/factors/questions",
"hints": {"allow": ["GET"
]
}
},
"self": {"href": "https://{yourOktaDomain}/api/v1/users/00u15s1KDETTQMQYABRL/factors/ufs2bysphxKODSZKWVCT",
"hints": {"allow": ["GET",
"DELETE"
]
}
},
"user": {"href": "https://{yourOktaDomain}/api/v1/users/00u15s1KDETTQMQYABRL",
"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",
"href": "https://{yourOktaDomain}/api/v1/users/00u15s1KDETTQMQYABRL/factors/ostf2gsyictRQDSGTDZE/lifecycle/activate",
"hints": {"allow": ["POST"
]
}
},
"self": {"href": "https://{yourOktaDomain}/api/v1/users/00u15s1KDETTQMQYABRL/factors/ostf2gsyictRQDSGTDZE",
"hints": {"allow": ["GET"
]
}
},
"user": {"href": "https://{yourOktaDomain}/api/v1/users/00u15s1KDETTQMQYABRL",
"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": {"href": "https://{yourOktaDomain}/api/v1/users/00u15s1KDETTQMQYABRL/factors/sms2gt8gzgEBPUWBIFHN/verify",
"hints": {"allow": ["POST"
]
}
},
"self": {"href": "https://{yourOktaDomain}/api/v1/users/00u15s1KDETTQMQYABRL/factors/sms2gt8gzgEBPUWBIFHN",
"hints": {"allow": ["GET",
"DELETE"
]
}
},
"user": {"href": "https://{yourOktaDomain}/api/v1/users/00u15s1KDETTQMQYABRL",
"hints": {"allow": ["GET"
]
}
}
}
}
]

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

Enum: "OKTA" "CUSTOM" "DUO" "FIDO" "GOOGLE" "RSA" "SYMANTEC" "YUBICO"

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": {"factorType": "question",
"provider": "OKTA",
"profile": {"question": "disliked_food",
"answer": "mayonnaise"
}
}
}
}

Response samples

application/json

{"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": {"href": "https://{yourOktaDomain}/api/v1/users/00u15s1KDETTQMQYABRL/factors/questions",
"hints": {"allow": ["GET"
]
}
},
"self": {"href": "https://{yourOktaDomain}/api/v1/users/00u15s1KDETTQMQYABRL/factors/ufs1o01OTMGHLAJPVHDZ",
"hints": {"allow": ["GET",
"DELETE"
]
}
},
"user": {"href": "https://{yourOktaDomain}/api/v1/users/00u15s1KDETTQMQYABRL",
"hints": {"allow": ["GET"
]
}
}
}
}

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

[{"factorType": "question",
"provider": "OKTA",
"vendorName": "OKTA",
"_links": {"questions": {"href": "https://{yourOktaDomain}/api/v1/users/00u15s1KDETTQMQYABRL/factors/questions",
"hints": {"allow": ["GET"
]
}
},
"enroll": {"href": "https://{yourOktaDomain}/api/v1/users/00u15s1KDETTQMQYABRL/factors",
"hints": {"allow": ["POST"
]
}
}
}
},
{"factorType": "token:software:totp",
"provider": "OKTA",
"_links": {"enroll": {"href": "https://{yourOktaDomain}/api/v1/users/00u15s1KDETTQMQYABRL/factors",
"hints": {"allow": ["POST"
]
}
}
}
},
{"factorType": "token:software:totp",
"provider": "GOOGLE",
"_links": {"enroll": {"href": "https://{yourOktaDomain}/api/v1/users/00u15s1KDETTQMQYABRL/factors",
"hints": {"allow": ["POST"
]
}
}
}
},
{"factorType": "sms",
"provider": "OKTA",
"vendorName": "OKTA",
"_links": {"enroll": {"href": "https://{yourOktaDomain}/api/v1/users/00u15s1KDETTQMQYABRL/factors",
"hints": {"allow": ["POST"
]
}
}
},
"_embedded": {"phones": [{"id": "mblldntFJevYKbyQQ0g3",
"profile": {"phoneNumber": "+14081234567"
},
"status": "ACTIVE"
}
]
}
},
{"factorType": "call",
"provider": "OKTA",
"_links": {"enroll": {"href": "https://{yourOktaDomain}/api/v1/users/00u15s1KDETTQMQYABRL/factors",
"hints": {"allow": ["POST"
]
}
}
}
},
{"factorType": "token",
"provider": "RSA",
"_links": {"enroll": {"href": "https://{yourOktaDomain}/api/v1/users/00u15s1KDETTQMQYABRL/factors",
"hints": {"allow": ["POST"
]
}
}
}
},
{"factorType": "token",
"provider": "SYMANTEC",
"_links": {"enroll": {"href": "https://{yourOktaDomain}/api/v1/users/00u15s1KDETTQMQYABRL/factors",
"hints": {"allow": ["POST"
]
}
}
}
}
]

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

{"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": {"href": "https://{yourOktaDomain}/api/v1/users/00u15s1KDETTQMQYABRL/factors/sms2gt8gzgEBPUWBIFHN/verify",
"hints": {"allow": ["POST"
]
}
},
"self": {"href": "https://{yourOktaDomain}/api/v1/users/00u15s1KDETTQMQYABRL/factors/sms2gt8gzgEBPUWBIFHN",
"hints": {"allow": ["GET",
"DELETE"
]
}
},
"user": {"href": "https://{yourOktaDomain}/api/v1/users/00u15s1KDETTQMQYABRL",
"hints": {"allow": ["GET"
]
}
}
}
}

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

{"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": {"href": "https://{yourOktaDomain}/api/v1/users/00u15s1KDETTQMQYABRL/factors/ostf1fmaMGJLMNGNLIVG/verify",
"hints": {"allow": ["POST"
]
}
},
"self": {"href": "https://{yourOktaDomain}/api/v1/users/00u15s1KDETTQMQYABRL/factors/ostf1fmaMGJLMNGNLIVG",
"hints": {"allow": ["GET",
"DELETE"
]
}
},
"user": {"href": "https://{yourOktaDomain}/api/v1/users/00u15s1KDETTQMQYABRL",
"hints": {"allow": ["GET"
]
}
}
}
}

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

Enum: "OKTA" "CUSTOM" "DUO" "FIDO" "GOOGLE" "RSA" "SYMANTEC" "YUBICO"

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

{"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": {"href": "https://{yourOktaDomain}/api/v1/users/00u15s1KDETTQMQYABRL/factors/mbl1nz9JHJGHWRKMTLHP/lifecycle/activate",
"hints": {"allow": ["POST"
]
}
},
"resend": [{"name": "sms",
"href": "https://{yourOktaDomain}/api/v1/users/00u15s1KDETTQMQYABRL/factors/mbl1nz9JHJGHWRKMTLHP/resend",
"hints": {"allow": ["POST"
]
}
}
],
"self": {"href": "https://{yourOktaDomain}/api/v1/users/00u15s1KDETTQMQYABRL/factors/mbl1nz9JHJGHWRKMTLHP",
"hints": {"allow": ["GET"
]
}
},
"user": {"href": "https://{yourOktaDomain}/api/v1/users/00u15s1KDETTQMQYABRL",
"hints": {"allow": ["GET"
]
}
}
}
}

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

{"expiresAt": "2015-04-01T15:57:32.000Z",
"factorResult": "WAITING",
"profile": {"credentialId": "jane.doe@example.com"
},
"_links": {"poll": {"href": "https://{yourOktaDomain}/api/v1/users/00u15s1KDETTQMQYABRL/factors/opfh52xcuft3J4uZc0g3/transactions/v2mst.GldKV5VxTrifyeZmWSQguA",
"hints": {"allow": ["GET"
]
}
},
"cancel": {"href": "https://{yourOktaDomain}/api/v1/users/00u15s1KDETTQMQYABRL/factors/opfh52xcuft3J4uZc0g3/transactions/v2mst.GldKV5VxTrifyeZmWSQguA",
"hints": {"allow": ["DELETE"
]
}
}
}
}

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

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": "123456"
}

Response samples

application/json

{"factorResult": "SUCCESS"
}

Social
CONTACT & LEGAL
MORE INFORMATION
okta.com
Products, case studies, resources
Help Center
Knowledgebase, roadmaps, and more
Trust
System status, security, compliance

User Factors

List all YubiKey OTP tokensOAuth 2.0: okta.users.read

query Parameters

Upload a YubiKey OTP seedOAuth 2.0: okta.users.manage

query Parameters

Request Body schema: application/jsonrequired

Retrieve a YubiKey OTP tokenOAuth 2.0: okta.users.read

path Parameters

List all enrolled factorsOAuth 2.0: okta.users.read

path Parameters

Enroll a factorOAuth 2.0: okta.users.manage

Additional SMS/Call factor information

Additional WebAuthn factor information

Additional Custom TOTP factor information

path Parameters

query Parameters

header Parameters

Request Body schema: application/jsonrequired

List all supported factorsOAuth 2.0: okta.users.read

path Parameters

List all supported security questionsCORS

path Parameters

Retrieve a factorOAuth 2.0: okta.users.read

path Parameters

Unenroll a factorOAuth 2.0: okta.users.manage

path Parameters

query Parameters

Activate a factorOAuth 2.0: okta.users.manage

path Parameters

Request Body schema: application/jsonoptional

Resend a factor enrollmentOAuth 2.0: okta.users.manage

path Parameters

query Parameters

Request Body schema: application/jsonrequired

Retrieve a factor transaction statusOAuth 2.0: okta.users.read

path Parameters

Verify a factorOAuth 2.0: okta.users.manage

path Parameters

query Parameters

header Parameters

Request Body schema: application/jsonoptional

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

Upload a YubiKey OTP seed
OAuth 2.0: `okta.users.manage`

Request Body schema: application/json
required

Retrieve a YubiKey OTP token
OAuth 2.0: `okta.users.read`

List all enrolled factors
OAuth 2.0: `okta.users.read`

Enroll a factor
OAuth 2.0: `okta.users.manage`

Request Body schema: application/json
required

List all supported factors
OAuth 2.0: `okta.users.read`

List all supported security questions
CORS

Retrieve a factor
OAuth 2.0: `okta.users.read`

Unenroll a factor
OAuth 2.0: `okta.users.manage`

Activate a factor
OAuth 2.0: `okta.users.manage`

Request Body schema: application/json
optional

Resend a factor enrollment
OAuth 2.0: `okta.users.manage`

Request Body schema: application/json
required

Retrieve a factor transaction status
OAuth 2.0: `okta.users.read`

Verify a factor
OAuth 2.0: `okta.users.manage`

Request Body schema: application/json
optional