Authenticators

The Authenticators Administration API provides operations to configure which authenticators are available to end users for use when they sign in to apps.

End users are required to use one or more authenticators based on the security requirements of the authentication policy.

Okta Identity Engine currently supports authenticators for the following factors:

Knowledge-based:

  • Password
  • Security Question

Possession-based:

  • Phone (SMS, voice call)
  • Email
  • WebAuthn
  • Duo
  • Custom app

Retrieve the well-known app authenticator configuration

Retrieves the well-known app authenticator configuration. Includes an app authenticator's settings, supported methods, and other details.

Request
query Parameters
oauthClientId
required
string

Filters app authenticator configurations by oauthClientId

Responses
200

Success

400

Bad Request

429

Too Many Requests

get/.well-known/app-authenticator-configuration
Request samples
Response samples
application/json
[
  • {
    • "authenticatorId": "aut22f6xzargnJZYE3l7",
    • "orgId": "00o1vhf34q20MfCFC3l7",
    • "type": "app",
    • "key": "custom_app",
    • "name": "EnergyAus Authenticator",
    • "createdDate": "2022-10-11T08:56:45.000Z",
    • "lastUpdated": "2023-09-07T11:31:35.000Z",
    • "settings": {
      },
    • "supportedMethods": [
      ],
    }
]

List all authenticators
Identity Engine
OAuth 2.0: okta.authenticators.read

Lists all authenticators

Responses
200

Success

403

Forbidden

429

Too Many Requests

get/api/v1/authenticators
Request samples
Response samples
application/json
[]

Create an authenticator
Identity Engine
OAuth 2.0: okta.authenticators.manage

Creates an authenticator

Request
query Parameters
activate
boolean
Default: true

Whether to execute the activation lifecycle operation when Okta creates the authenticator

Request Body schema: application/json
required
key
string (AuthenticatorKeyEnum)

A human-readable string that identifies the authenticator

name
string

Display name of the authenticator

status
string (LifecycleStatus)
Enum: "ACTIVE" "INACTIVE"
type
string (AuthenticatorType)

The type of authenticator

Enum: "app" "email" "federated" "password" "phone" "security_key" "security_question"
agreeToTerms
boolean

A value of true indicates that the administrator accepts the termsfor creating a new authenticator. Okta requires that you accept the terms when creating a new custom_app authenticator. Other authenticators don't require this field.

object
type
string

Provider type

Value: "PUSH"
object

The configuration of the provider

object
object
object
userVerification
string (CustomAppUserVerificationEnum)

User verification setting

Enum: "PREFERRED" "REQUIRED"
appInstanceId
string

The application instance ID. For custom_app, you need to create an OIDC native app using the Apps API with Authorization Code and Refresh Token grant types. You can leave both Sign-in redirect URIs and Sign-out redirect URIs as the default values.

Responses
200

OK

400

Bad Request

403

Forbidden

429

Too Many Requests

post/api/v1/authenticators
Request samples
application/json
{
  • "key": "duo",
  • "name": "Duo Security",
  • "provider": {
    • "type": "DUO",
    • "configuration": {}
    }
}
Response samples
application/json
{}

Retrieve an authenticator
Identity Engine
OAuth 2.0: okta.authenticators.read

Retrieves an authenticator from your Okta organization by authenticatorId

Request
path Parameters
authenticatorId
required
string

id of the authenticator

Example: aut1nd8PQhGcQtSxB0g4
Responses
200

OK

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/authenticators/{authenticatorId}
Request samples
Response samples
application/json
{}

Replace an authenticator
Identity Engine
OAuth 2.0: okta.authenticators.manage

Replaces the properties for an authenticator identified by authenticatorId

Request
path Parameters
authenticatorId
required
string

id of the authenticator

Example: aut1nd8PQhGcQtSxB0g4
Request Body schema: application/json
required
key
string (AuthenticatorKeyEnum)

A human-readable string that identifies the authenticator

name
string

Display name of the authenticator

status
string (LifecycleStatus)
Enum: "ACTIVE" "INACTIVE"
type
string (AuthenticatorType)

The type of authenticator

Enum: "app" "email" "federated" "password" "phone" "security_key" "security_question"
agreeToTerms
boolean

A value of true indicates that the administrator accepts the termsfor creating a new authenticator. Okta requires that you accept the terms when creating a new custom_app authenticator. Other authenticators don't require this field.

object
type
string

Provider type

Value: "PUSH"
object

The configuration of the provider

object
object
object
userVerification
string (CustomAppUserVerificationEnum)

User verification setting

Enum: "PREFERRED" "REQUIRED"
appInstanceId
string

The application instance ID. For custom_app, you need to create an OIDC native app using the Apps API with Authorization Code and Refresh Token grant types. You can leave both Sign-in redirect URIs and Sign-out redirect URIs as the default values.

Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

429

Too Many Requests

put/api/v1/authenticators/{authenticatorId}
Request samples
application/json
{
  • "key": "duo",
  • "name": "Duo Security",
  • "provider": {
    • "type": "DUO",
    • "configuration": {}
    }
}
Response samples
application/json
{}

Activate an authenticator
Identity Engine
OAuth 2.0: okta.authenticators.manage

Activates an authenticator by authenticatorId

Request
path Parameters
authenticatorId
required
string

id of the authenticator

Example: aut1nd8PQhGcQtSxB0g4
Responses
200

OK

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/authenticators/{authenticatorId}/lifecycle/activate
Request samples
Response samples
application/json
{}

Deactivate an authenticator
Identity Engine
OAuth 2.0: okta.authenticators.manage

Deactivates an authenticator by authenticatorId

Request
path Parameters
authenticatorId
required
string

id of the authenticator

Example: aut1nd8PQhGcQtSxB0g4
Responses
200

OK

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/authenticators/{authenticatorId}/lifecycle/deactivate
Request samples
Response samples
application/json
{}

List all methods of an authenticator
Identity Engine
OAuth 2.0: okta.authenticators.read

Lists all methods of an authenticator identified by authenticatorId

Note: The AAGUID Group object supports the Early Access (Self-Service) Allow List for FIDO2 (WebAuthn) Authenticators feature. Enable the feature for your org from the Settings > Features page in the Admin Console. This feature has several limitations when enrolling a security key:

  • Enrollment is currently unsupported on Firefox.
  • Enrollment is currently unsupported on Chrome if User Verification is set to DISCOURAGED and a PIN is set on the security key.
  • If prompted during enrollment, users must allow Okta to see the make and model of the security key.
Request
path Parameters
authenticatorId
required
string

id of the authenticator

Example: aut1nd8PQhGcQtSxB0g4
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/authenticators/{authenticatorId}/methods
Request samples
Response samples
application/json
[]

Retrieve an authenticator method
Identity Engine
OAuth 2.0: okta.authenticators.read

Retrieves a method identified by methodType of an authenticator identified by authenticatorId

Note: The AAGUID Group object supports the Early Access (Self-Service) Allow List for FIDO2 (WebAuthn) Authenticators feature. Enable the feature for your org from the Settings > Features page in the Admin Console. This feature has several limitations when enrolling a security key:

  • Enrollment is currently unsupported on Firefox.
  • Enrollment is currently unsupported on Chrome if User Verification is set to DISCOURAGED and a PIN is set on the security key.
  • If prompted during enrollment, users must allow Okta to see the make and model of the security key.
Request
path Parameters
authenticatorId
required
string

id of the authenticator

Example: aut1nd8PQhGcQtSxB0g4
methodType
required
string (AuthenticatorMethodType)

Type of authenticator method

Enum: "cert" "duo" "email" "idp" "otp" "password" "push" "security_question" "signed_nonce" "sms" "totp" "voice" "webauthn"
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/authenticators/{authenticatorId}/methods/{methodType}
Request samples
Response samples
application/json
{}

Replace an authenticator method
Identity Engine
OAuth 2.0: okta.authenticators.manage

Replaces a method of methodType for an authenticator identified by authenticatorId

Note: The AAGUID Group object supports the Early Access (Self-Service) Allow List for FIDO2 (WebAuthn) Authenticators feature. Enable the feature for your org from the Settings > Features page in the Admin Console. This feature has several limitations when enrolling a security key:

  • Enrollment is currently unsupported on Firefox.
  • Enrollment is currently unsupported on Chrome if User Verification is set to DISCOURAGED and a PIN is set on the security key.
  • If prompted during enrollment, users must allow Okta to see the make and model of the security key.
Request
path Parameters
authenticatorId
required
string

id of the authenticator

Example: aut1nd8PQhGcQtSxB0g4
methodType
required
string (AuthenticatorMethodType)

Type of authenticator method

Enum: "cert" "duo" "email" "idp" "otp" "password" "push" "security_question" "signed_nonce" "sms" "totp" "voice" "webauthn"
Request Body schema: application/json
status
string (LifecycleStatus)
Enum: "ACTIVE" "INACTIVE"
type
string (AuthenticatorMethodType)

The type of authenticator method

Responses
200

Success

400

Bad Request

403

Forbidden

404

Not Found

429

Too Many Requests

put/api/v1/authenticators/{authenticatorId}/methods/{methodType}
Request samples
application/json
{
  • "status": "ACTIVE",
  • "type": "sms"
}
Response samples
application/json
{}

Activate an authenticator method
Identity Engine
OAuth 2.0: okta.authenticators.manage

Activates a method for an authenticator identified by authenticatorId and methodType

Note: The AAGUID Group object supports the Early Access (Self-Service) Allow List for FIDO2 (WebAuthn) Authenticators feature. Enable the feature for your org from the Settings > Features page in the Admin Console. This feature has several limitations when enrolling a security key:

  • Enrollment is currently unsupported on Firefox.
  • Enrollment is currently unsupported on Chrome if User Verification is set to DISCOURAGED and a PIN is set on the security key.
  • If prompted during enrollment, users must allow Okta to see the make and model of the security key.
Request
path Parameters
authenticatorId
required
string

id of the authenticator

Example: aut1nd8PQhGcQtSxB0g4
methodType
required
string (AuthenticatorMethodType)

Type of authenticator method

Enum: "cert" "duo" "email" "idp" "otp" "password" "push" "security_question" "signed_nonce" "sms" "totp" "voice" "webauthn"
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/authenticators/{authenticatorId}/methods/{methodType}/lifecycle/activate
Request samples
Response samples
application/json
{}

Deactivate an authenticator method
Identity Engine
OAuth 2.0: okta.authenticators.manage

Deactivates a method for an authenticator identified by authenticatorId and methodType

Note: The AAGUID Group object supports the Early Access (Self-Service) Allow List for FIDO2 (WebAuthn) Authenticators feature. Enable the feature for your org from the Settings > Features page in the Admin Console. This feature has several limitations when enrolling a security key:

  • Enrollment is currently unsupported on Firefox.
  • Enrollment is currently unsupported on Chrome if User Verification is set to DISCOURAGED and a PIN is set on the security key.
  • If prompted during enrollment, users must allow Okta to see the make and model of the security key.
Request
path Parameters
authenticatorId
required
string

id of the authenticator

Example: aut1nd8PQhGcQtSxB0g4
methodType
required
string (AuthenticatorMethodType)

Type of authenticator method

Enum: "cert" "duo" "email" "idp" "otp" "password" "push" "security_question" "signed_nonce" "sms" "totp" "voice" "webauthn"
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/authenticators/{authenticatorId}/methods/{methodType}/lifecycle/deactivate
Request samples
Response samples
application/json
{}