Authenticators

The Authenticators Administration API provides operations to configure which Authenticators are available to end users for use when signing in to applications.

End users are required to use one or more Authenticators depending 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, which includes an app authenticator's settings, supported methods and various other configuration 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
[
  • {
    • "appAuthenticatorEnrollEndpoint": "string",
    • "authenticatorId": "string",
    • "createdDate": "2019-08-24T14:15:22Z",
    • "key": "string",
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "name": "string",
    • "orgId": "string",
    • "settings": {
      },
    • "supportedMethods": [
      ],
    • "type": "app"
    }
]

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

Lists all authenticators

Request
query Parameters
expand
Array of strings

Specifies additional metadata for the response

Items Enum: "methods" "authenticationPolicy"
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: false

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

Request Body schema: application/json
required
key
string
name
string
object (AuthenticatorProvider)
object (AuthenticatorProviderConfiguration)
authPort
integer
hostName
string
instanceId
string
sharedSecret
string
object (AuthenticatorProviderConfigurationUserNameTemplate)
type
string
object (AuthenticatorSettings)
allowedFor
string (AllowedForEnum)
Enum: "any" "none" "recovery" "sso"
appInstanceId
string
object (ChannelBinding)
required
string (RequiredEnum)
Enum: "ALWAYS" "HIGH_RISK_ONLY" "NEVER"
style
string
object (Compliance)
fips
string (FipsEnum)
Enum: "OPTIONAL" "REQUIRED"
tokenLifetimeInMinutes
integer
userVerification
string (UserVerificationEnum)

User verification setting

Enum: "DISCOURAGED" "PREFERRED" "REQUIRED"
status
string (LifecycleStatus)
Enum: "ACTIVE" "INACTIVE"
type
string (AuthenticatorType)
Enum: "app" "email" "federated" "password" "phone" "security_key" "security_question"
object
Array of objects (AuthenticatorMethodBase)
Array
status
string (LifecycleStatus)
Enum: "ACTIVE" "INACTIVE"
type
string (AuthenticatorMethodType)
Array of objects (Policy)
Array
description
string
name
string
priority
integer
status
string (LifecycleStatus)
Enum: "ACTIVE" "INACTIVE"
system
boolean
type
string (PolicyType)
object (PolicyRuleConditions)
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
query Parameters
expand
Array of strings

Specifies additional metadata for the response

Items Enum: "methods" "authenticationPolicy"
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
name
string
object (AuthenticatorProvider)
object (AuthenticatorProviderConfiguration)
authPort
integer
hostName
string
instanceId
string
sharedSecret
string
object (AuthenticatorProviderConfigurationUserNameTemplate)
type
string
object (AuthenticatorSettings)
allowedFor
string (AllowedForEnum)
Enum: "any" "none" "recovery" "sso"
appInstanceId
string
object (ChannelBinding)
required
string (RequiredEnum)
Enum: "ALWAYS" "HIGH_RISK_ONLY" "NEVER"
style
string
object (Compliance)
fips
string (FipsEnum)
Enum: "OPTIONAL" "REQUIRED"
tokenLifetimeInMinutes
integer
userVerification
string (UserVerificationEnum)

User verification setting

Enum: "DISCOURAGED" "PREFERRED" "REQUIRED"
status
string (LifecycleStatus)
Enum: "ACTIVE" "INACTIVE"
type
string (AuthenticatorType)
Enum: "app" "email" "federated" "password" "phone" "security_key" "security_question"
object
Array of objects (AuthenticatorMethodBase)
Array
status
string (LifecycleStatus)
Enum: "ACTIVE" "INACTIVE"
type
string (AuthenticatorMethodType)
Array of objects (Policy)
Array
description
string
name
string
priority
integer
status
string (LifecycleStatus)
Enum: "ACTIVE" "INACTIVE"
system
boolean
type
string (PolicyType)
object (PolicyRuleConditions)
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

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
[
  • {
    • "status": "ACTIVE",
    • "type": "cert",
    • "_links": {
      }
    }
]

Retrieve a Method
Identity Engine
OAuth 2.0: okta.authenticators.read

Retrieves a Method identified by methodType of an Authenticator identified by authenticatorId

Request
path Parameters
authenticatorId
required
string

id of the Authenticator

Example: aut1nd8PQhGcQtSxB0g4
methodType
required
string (AuthenticatorMethodType)

Type of the 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
{
  • "status": "ACTIVE",
  • "type": "sms",
  • "_links": {
    • "self": {
      },
    • "activate": {
      },
    • "deactivate": {
      }
    }
}

Replace a Method
Identity Engine
OAuth 2.0: okta.authenticators.manage

Replaces a Method of methodType for an Authenticator identified by authenticatorId

Request
path Parameters
authenticatorId
required
string

id of the Authenticator

Example: aut1nd8PQhGcQtSxB0g4
methodType
required
string (AuthenticatorMethodType)

Type of the 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)
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
{
  • "status": "ACTIVE",
  • "type": "sms",
  • "_links": {
    • "self": {
      },
    • "activate": {
      },
    • "deactivate": {
      }
    }
}

Activate an Authenticator Method
Identity Engine
OAuth 2.0: okta.authenticators.manage

Activates a Method for an Authenticator identified by authenticatorId and methodType

Request
path Parameters
authenticatorId
required
string

id of the Authenticator

Example: aut1nd8PQhGcQtSxB0g4
methodType
required
string (AuthenticatorMethodType)

Type of the 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
{
  • "status": "ACTIVE",
  • "type": "sms",
  • "_links": {
    • "self": {
      },
    • "activate": {
      },
    • "deactivate": {
      }
    }
}

Deactivate an Authenticator Method
Identity Engine
OAuth 2.0: okta.authenticators.manage

Deactivates a Method for an Authenticator identified by authenticatorId and methodType

Request
path Parameters
authenticatorId
required
string

id of the Authenticator

Example: aut1nd8PQhGcQtSxB0g4
methodType
required
string (AuthenticatorMethodType)

Type of the 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
{
  • "status": "ACTIVE",
  • "type": "sms",
  • "_links": {
    • "self": {
      },
    • "activate": {
      },
    • "deactivate": {
      }
    }
}