Skip to main content

factors

Creates, updates, deletes, gets or lists a factors resource.

Overview​

Namefactors
TypeResource
Idokta.users.factors

Fields​

The following fields are returned by SELECT queries:

NameDatatypeDescription
idstringID of the factor (example: caf8m6jbcvUH8mAep1d7)
_embeddedobject
_linksobjectSpecifies link relations (see Web Linking) available using the JSON Hypertext Application Language specification. This object is used for dynamic discovery of related resources and lifecycle operations.
createdstring (date-time)Timestamp when the factor was enrolled (example: 2022-08-25T00:31:00.000Z)
factorTypestringType of factor
lastUpdatedstring (date-time)Timestamp when the factor was last updated (example: 2022-08-25T00:31:00.000Z)
profileobjectSpecific attributes related to the factor
providerstringProvider for the factor. Each provider can support a subset of factor types.
statusstringStatus of the factor (example: ACTIVE)
vendorNamestringName of the factor vendor. This is usually the same as the provider except for On-Prem MFA, which depends on admin settings. (example: OKTA)

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
list_factorsselectsubdomainLists all enrolled factors for the specified user that are included in the highest priority authenticator enrollment policy that applies to the user.

Only enrolled factors that are REQUIRED or OPTIONAL in the highest priority authenticator enrollment policy can be returned.

> Note: When admins use this endpoint for other users, the authenticator enrollment policy that's evaluated can vary depending on how client-specific conditions are configured in the rules of an authenticator enrollment policy. The client-specific conditions of the admin's client are used during policy evaluation instead of the client-specific conditions of the user. This can affect which authenticator enrollment policy is evaluated and which factors are returned.
>
> For example, an admin in Europe lists all enrolled factors for a user in North America. The network zone of the admin's client (in Europe) is used during policy evaluation instead of the network zone of the user (in North America).
get_factorselectsubdomainRetrieves an existing factor for the specified user
get_factor_transaction_statusselectsubdomainRetrieves the status of a push factor verification transaction

> Note:
> The response body for a number matching push challenge to an Okta Verify push factor enrollment is different from the response body of a standard push challenge.
> The number matching push challenge response body contains the correct answer for the challenge.
> Use Verify a factor to configure which challenge is sent.
enroll_factorinsertsubdomainupdatePhone, templateId, tokenLifetimeSeconds, activate, Accept-LanguageEnrolls a supported factor for the specified user

> Notes:
> * All responses return the enrolled factor with a status of either PENDING_ACTIVATION or ACTIVE.
> * You can't use the Factors API to enroll Okta Fastpass (signed_nonce) for a user. See Configure Okta Fastpass.

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

* <x-lifecycle class="oie"></x-lifecycle>
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.
unenroll_factordeletesubdomainremoveRecoveryEnrollmentUnenrolls 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.
activate_factorexecsubdomainActivates 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.

> Notes:
> * If the user exceeds their SMS, call, or email factor activation rate limit, then an [OTP resend request]https://developer.okta.com/docs/api/openapi/okta-management/management/tag/UserFactor/ isn't allowed for the same factor.
> * You can't use the Factors API to activate Okta Fastpass (signed_nonce) for a user. See Configure Okta Fastpass.
resend_enroll_factorexecsubdomaintemplateIdResends 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]https://developer.okta.com/docs/api/openapi/okta-management/management/tag/UserFactor/.
verify_factorexecsubdomaintemplateId, tokenLifetimeSeconds, X-Forwarded-For, User-Agent, Accept-LanguageVerifies 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.

> Notes:
> - You can send standard push challenges or number matching push challenges to Okta Verify push factor enrollments. Use a request body for number matching push challenges.
> - To verify a push factor, use the poll link returned when you issue the challenge. See Retrieve a factor transaction status.

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
subdomainstringThe domain of your organization. This can be a provided subdomain of an official okta domain (okta.com, oktapreview.com, etc) or one of your configured custom domains. (default: my-org)
Accept-LanguagestringAn 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.
User-AgentstringType of user agent detected when the request is made. Required to verify push factors.
X-Forwarded-ForstringPublic IP address for the user agent
activatebooleanIf 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.
removeRecoveryEnrollmentbooleanIf true, removes the phone number as both a recovery method and a factor. This parameter is only used for the sms and call factors.
templateIdstringID of an existing custom SMS template. See the [SMS Templates API]https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Template/. This parameter is only used by sms factors.
tokenLifetimeSecondsinteger (int32)Defines how long the token remains valid
updatePhonebooleanIf 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.

SELECT examples​

Lists all enrolled factors for the specified user that are included in the highest priority authenticator enrollment policy that applies to the user.

Only enrolled factors that are REQUIRED or OPTIONAL in the highest priority authenticator enrollment policy can be returned.

> Note: When admins use this endpoint for other users, the authenticator enrollment policy that's evaluated can vary depending on how client-specific conditions are configured in the rules of an authenticator enrollment policy. The client-specific conditions of the admin's client are used during policy evaluation instead of the client-specific conditions of the user. This can affect which authenticator enrollment policy is evaluated and which factors are returned.
>
> For example, an admin in Europe lists all enrolled factors for a user in North America. The network zone of the admin's client (in Europe) is used during policy evaluation instead of the network zone of the user (in North America).

SELECT
id,
_embedded,
_links,
created,
factorType,
lastUpdated,
profile,
provider,
status,
vendorName
FROM okta.users.factors
WHERE subdomain = '{{ subdomain }}' -- required;

INSERT examples​

Enrolls a supported factor for the specified user

> Notes:
> * All responses return the enrolled factor with a status of either PENDING_ACTIVATION or ACTIVE.
> * You can't use the Factors API to enroll Okta Fastpass (signed_nonce) for a user. See Configure Okta Fastpass.

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

* <x-lifecycle class="oie"></x-lifecycle>
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.

INSERT INTO okta.users.factors (
data__factorType,
data__profile,
data__provider,
subdomain,
updatePhone,
templateId,
tokenLifetimeSeconds,
activate,
Accept-Language
)
SELECT 
'{{ factorType }}',
'{{ profile }}',
'{{ provider }}',
'{{ subdomain }}',
'{{ updatePhone }}',
'{{ templateId }}',
'{{ tokenLifetimeSeconds }}',
'{{ activate }}',
'{{ Accept-Language }}'
RETURNING
id,
_embedded,
_links,
created,
factorType,
lastUpdated,
profile,
provider,
status,
vendorName
;

DELETE examples​

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.

DELETE FROM okta.users.factors
WHERE subdomain = '{{ subdomain }}' --required
AND removeRecoveryEnrollment = '{{ removeRecoveryEnrollment }}';

Lifecycle Methods​

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.

> Notes:
> * If the user exceeds their SMS, call, or email factor activation rate limit, then an [OTP resend request]https://developer.okta.com/docs/api/openapi/okta-management/management/tag/UserFactor/ isn't allowed for the same factor.
> * You can't use the Factors API to activate Okta Fastpass (signed_nonce) for a user. See Configure Okta Fastpass.

EXEC okta.users.factors.activate_factor 
@subdomain='{{ subdomain }}' --required;