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
  • Temporary access code (TAC)

Possession-based:

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

Note: There are several limitations when you create or modify a webauthn authenticator. See Configure the FIDO2 (WebAuthn) authenticator and FIDO2 (WebAuthn) support and behavior.

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": [
      ],
    • "appAuthenticatorEnrollEndpoint": "https://{yourOktaDomain}/idp/myaccount/app-authenticators"
    }
]
List all authenticators
Identity Engine
OAuth 2.0 scopes: 
  • 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 scopes: 
  • 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" "tac"  
agreeToTerms
boolean
A value of true indicates that the administrator accepts the terms for 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 scopes: 
  • 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 scopes: 
  • 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" "tac"  
agreeToTerms
boolean
A value of true indicates that the administrator accepts the terms for 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
{}
List all custom AAGUIDs
Early Access
OAuth 2.0 scopes: 
  • okta.authenticators.read
Lists all custom Authenticator Attestation Global Unique Identifiers (AAGUIDs) in the org


Only custom AAGUIDs that an admin has created are returned.


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}/aaguids
Request samples 
Response samples 
application/json
[
  • {
    • "aaguid": "cb69481e-8ff7-4039-93ec-0a272911111",
    • "name": "My Security Key",
    • "authenticatorCharacteristics": {
      },
    • "attestationRootCertificates": [
      ],
    • "_links": {}
    }
]
Create a custom AAGUID
Early Access
OAuth 2.0 scopes: 
  • okta.authenticators.manage
Creates a custom AAGUID for the WebAuthn authenticator


Request 
path Parameters
authenticatorId
required
string
id of the authenticator


 
 Example:  aut1nd8PQhGcQtSxB0g4
Request Body schema: application/json
aaguid
string
An Authenticator Attestation Global Unique Identifier (AAGUID) is a 128-bit identifier indicating the model.


 
Array of objects (AttestationRootCertificatesRequest) 
Contains the certificate and information about it


 
 Array 
x5c
string
X.509 certificate chain


 
object (AAGUIDAuthenticatorCharacteristics) 
Contains additional properties about custom AAGUID.


 
fipsCompliant
boolean
Indicates whether the authenticator meets Federal Information Processing Standards (FIPS) compliance requirements


 
hardwareProtected
boolean
Indicates whether the authenticator stores the private key on a hardware component


 
platformAttached
boolean
Indicates whether the custom AAGUID is built into the authenticator (true) or if it's a separate, external authenticator


 
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/authenticators/{authenticatorId}/aaguids
Request samples 
application/json
{
  • "aaguid": "cb69481e-8ff7-4039-93ec-0a272911111",
  • "name": "My Security Key",
  • "authenticatorCharacteristics": {
    • "platformAttached": false,
    • "fipsCompliant": false,
    • "hardwareProtected": false
    },
  • "attestationRootCertificates": [
    • {
      }
    ]
}
Response samples 
application/json
{
  • "aaguid": "cb69481e-8ff7-4039-93ec-0a272911111",
  • "name": "My Security Key",
  • "authenticatorCharacteristics": {
    • "platformAttached": false,
    • "fipsCompliant": false,
    • "hardwareProtected": false
    },
  • "attestationRootCertificates": [
    • {
      }
    ],
  • "_links": {}
}
Retrieve a custom AAGUID
Early Access
OAuth 2.0 scopes: 
  • okta.authenticators.read
Retrieves a custom AAGUID


Request 
path Parameters
authenticatorId
required
string
id of the authenticator


 
 Example:  aut1nd8PQhGcQtSxB0g4
aaguid
required
string
Unique ID of a custom AAGUID


 
 Example:  cb69481e-8ff7-4039-93ec-0a272911111
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/authenticators/{authenticatorId}/aaguids/{aaguid}
Request samples 
Response samples 
application/json
{
  • "aaguid": "cb69481e-8ff7-4039-93ec-0a272911111",
  • "name": "My Security Key",
  • "authenticatorCharacteristics": {
    • "platformAttached": false,
    • "fipsCompliant": false,
    • "hardwareProtected": false
    },
  • "attestationRootCertificates": [
    • {
      }
    ],
  • "_links": {}
}
Replace a custom AAGUID
Early Access
OAuth 2.0 scopes: 
  • okta.authenticators.manage
Replaces a custom AAGUID for the specified WebAuthn authenticator


Request 
path Parameters
authenticatorId
required
string
id of the authenticator


 
 Example:  aut1nd8PQhGcQtSxB0g4
aaguid
required
string
Unique ID of a custom AAGUID


 
 Example:  cb69481e-8ff7-4039-93ec-0a272911111
Request Body schema: application/json
Array of objects (AttestationRootCertificatesRequest) 
Contains the certificate and information about it


 
 Array 
x5c
string
X.509 certificate chain


 
object (AAGUIDAuthenticatorCharacteristics) 
Contains additional properties about custom AAGUID.


 
fipsCompliant
boolean
Indicates whether the authenticator meets Federal Information Processing Standards (FIPS) compliance requirements


 
hardwareProtected
boolean
Indicates whether the authenticator stores the private key on a hardware component


 
platformAttached
boolean
Indicates whether the custom AAGUID is built into the authenticator (true) or if it's a separate, external authenticator


 
name
string
The product name associated with this AAGUID.


 
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


put/api/v1/authenticators/{authenticatorId}/aaguids/{aaguid}
Request samples 
application/json
{
  • "name": "My Security Key",
  • "authenticatorCharacteristics": {
    • "platformAttached": false,
    • "fipsCompliant": false,
    • "hardwareProtected": false
    },
  • "attestationRootCertificates": [
    • {
      }
    ]
}
Response samples 
application/json
{
  • "aaguid": "cb69481e-8ff7-4039-93ec-0a272911111",
  • "name": "My Security Key",
  • "authenticatorCharacteristics": {
    • "platformAttached": false,
    • "fipsCompliant": false,
    • "hardwareProtected": false
    },
  • "attestationRootCertificates": [
    • {
      }
    ],
  • "_links": {}
}
Update a custom AAGUID
Early Access
OAuth 2.0 scopes: 
  • okta.authenticators.manage
Updates the properties of a custom AAGUID by the authenticatorId and aaguid ID


Request 
path Parameters
authenticatorId
required
string
id of the authenticator


 
 Example:  aut1nd8PQhGcQtSxB0g4
aaguid
required
string
Unique ID of a custom AAGUID


 
 Example:  cb69481e-8ff7-4039-93ec-0a272911111
Request Body schema: application/merge-patch+json
Array of objects (AttestationRootCertificatesRequest) 
Contains the certificate and information about it


 
 Array 
x5c
string
X.509 certificate chain


 
object (AAGUIDAuthenticatorCharacteristics) 
Contains additional properties about custom AAGUID.


 
fipsCompliant
boolean
Indicates whether the authenticator meets Federal Information Processing Standards (FIPS) compliance requirements


 
hardwareProtected
boolean
Indicates whether the authenticator stores the private key on a hardware component


 
platformAttached
boolean
Indicates whether the custom AAGUID is built into the authenticator (true) or if it's a separate, external authenticator


 
name
string
The product name associated with this AAGUID.


 
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


patch/api/v1/authenticators/{authenticatorId}/aaguids/{aaguid}
Request samples 
application/merge-patch+json
{
  • "name": "My Security Key",
  • "authenticatorCharacteristics": {
    • "platformAttached": false,
    • "fipsCompliant": false,
    • "hardwareProtected": false
    },
  • "attestationRootCertificates": [
    • {
      }
    ]
}
Response samples 
application/json
{
  • "aaguid": "cb69481e-8ff7-4039-93ec-0a272911111",
  • "name": "My Security Key",
  • "authenticatorCharacteristics": {
    • "platformAttached": false,
    • "fipsCompliant": false,
    • "hardwareProtected": false
    },
  • "attestationRootCertificates": [
    • {
      }
    ],
  • "_links": {}
}
Delete a custom AAGUID
Early Access
OAuth 2.0 scopes: 
  • okta.authenticators.manage
Deletes a custom AAGUID


You can only delete custom AAGUIDs that an admin has created.


Request 
path Parameters
authenticatorId
required
string
id of the authenticator


 
 Example:  aut1nd8PQhGcQtSxB0g4
aaguid
required
string
Unique ID of a custom AAGUID


 
 Example:  cb69481e-8ff7-4039-93ec-0a272911111
Responses 
204
Deleted


403
Forbidden


404
Not Found


429
Too Many Requests


delete/api/v1/authenticators/{authenticatorId}/aaguids/{aaguid}
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 an authenticator
Identity Engine
OAuth 2.0 scopes: 
  • 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 scopes: 
  • 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 scopes: 
  • 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
[]
Retrieve an authenticator method
Identity Engine
OAuth 2.0 scopes: 
  • 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 authenticator method


 Enum: "cert" "duo" "email" "idp" "otp" "password" "push" "security_question" "signed_nonce" "sms" "totp" "voice" "webauthn" "tac"  
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 scopes: 
  • 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 authenticator method


 Enum: "cert" "duo" "email" "idp" "otp" "password" "push" "security_question" "signed_nonce" "sms" "totp" "voice" "webauthn" "tac"  
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 scopes: 
  • 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 authenticator method


 Enum: "cert" "duo" "email" "idp" "otp" "password" "push" "security_question" "signed_nonce" "sms" "totp" "voice" "webauthn" "tac"  
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 scopes: 
  • 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 authenticator method


 Enum: "cert" "duo" "email" "idp" "otp" "password" "push" "security_question" "signed_nonce" "sms" "totp" "voice" "webauthn" "tac"  
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
{}