Authenticators Administration API

Identity Engine

The Authenticators Administration API enables an Org Administrator 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 Early Access

Note: Some of the curl code examples on this page include SSWS API token authentication. However, Okta recommends using scoped OAuth 2.0 and OIDC access tokens to authenticate with Okta management APIs. OAuth 2.0 and OIDC access tokens provide fine-grain control over the bearer's actions on specific endpoints. See Okta API authentication methods.

Get started

Explore the Authenticators Administration API: (opens new window)

Authenticators Administration operations

The Authenticators Administration API has the following CRUD operations:

• Create Authenticator
• List Authenticators
• Get an Authenticator by ID
• Update Authenticator settings
• Activate an Authenticator
• Deactivate an Authenticator
• List all Methods of an Authenticator
• Retrieve an Authenticator Method
• Replace an Authenticator Method
• Activate an Authenticator Method
• Deactivate an Authenticator Method

Create Authenticator

POST /api/v1/authenticators

Create an Authenticator

Note: You can use this operation as part of the "Create a custom authenticator" flow. See the Custom authenticator integration guide.

Request path parameters

N/A

Request query parameters

Note: The activate parameter is optional. If you don't include the activate parameter with a value of TRUE when creating an authenticator, you need to activate the authenticator later in the Admin Console or by using the Activate an Authenticator operation.

Parameter	Description	Param Type	DataType	Required	Default
activate	Executes the activation lifecycle operation when Okta creates the authenticator	Query	Boolean	FALSE	TRUE

Request body

An Authenticator Object that you need created

Response body

The created Authenticator

Use example

Returns the created Authenticator with an id value of aut9gnvcjUHIWb37J0g4:

Request

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
-d '{
    "key": "duo",
    "name": "Duo Security",
    "provider": {
        "type": "DUO",
        "configuration": {
            "userNameTemplate": {
                "template": "oktaId"
            },
            "integrationKey": "testIntegrationKey",
            "secretKey": "testSecretKey",
            "host":"https://api-xxxxxxxx.duosecurity.com"
        }
    }
}
' "https://{yourOktaDomain}/api/v1/authenticators"

Response

{
    "type": "app",
    "id": "aut9gnvcjUHIWb37J0g4",
    "key": "duo",
    "status": "ACTIVE",
    "name": "Duo Security",
    "created": "2022-07-15T21:14:02.000Z",
    "lastUpdated": "2022-07-15T21:14:02.000Z",
    "settings": {},
    "provider": {
        "type": "DUO",
        "configuration": {
            "host": "https://api-xxxxxxxx.duosecurity.com",
            "userNameTemplate": {
                "template": "oktaId"
            }
        }
    },
    "_links": {
        "self": {
            "href": "https://{yourOktaDomain}/api/v1/authenticators/aut5gnvcjUHIWb25J0g4",
            "hints": {
                "allow": [
                    "GET",
                    "PUT"
                ]
            }
        },
        "deactivate": {
            "href": "https://{yourOktaDomain}/api/v1/authenticators/aut5gnvcjUHIWb25J0g4/lifecycle/deactivate",
            "hints": {
                "allow": [
                    "POST"
                ]
            }
        },
        "methods": {
            "href": "https://{yourOktaDomain}/api/v1/authenticators/aut5gnvcjUHIWb25J0g4/methods",
            "hints": {
                "allow": [
                    "GET"
                ]
            }
        }
    }
}

List Authenticators

GET /api/v1/authenticators

Lists all available Authenticators

Request query parameters

N/A

Response body

An array of Authenticator Objects

Use example

This request returns all available Authenticators:

Request

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/authenticators"

Response

[
  {
    "type": "email",
    "id": "aut1nbsPHh7jNjjyP0g4",
    "key": "okta_email",
    "status": "ACTIVE",
    "name": "Email",
    "created": "2020-07-26T21:05:23.000Z",
    "lastUpdated": "2020-07-28T21:45:52.000Z",
    "settings": {
            "allowedFor": "any",
            "tokenLifetimeInMinutes": 5
     },
    "_links": {
      "self": {
        "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nbsPHh7jNjjyP0g4",
        "hints": {
          "allow": [
            "GET",
            "PUT"
          ]
        }
      },
      "methods": {
        "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nbsPHh7jNjjyP0g4/methods",
        "hints": {
          "allow": [
            "GET"
          ]
        }
      },
      "deactivate": {
        "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nbsPHh7jNjjyP0g4/lifecycle/deactivate",
        "hints": {
          "allow": [
            "POST"
          ]
        }
      }
    }
  },
  {
    "type": "password",
    "id": "aut1nbtrJKKA9m45a0g4",
    "key": "okta_password",
    "status": "ACTIVE",
    "name": "Password",
    "created": "2020-07-26T21:05:23.000Z",
    "lastUpdated": "2020-07-26T21:05:23.000Z",
    "_links": {
      "self": {
        "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nbtrJKKA9m45a0g4",
        "hints": {
          "allow": [
            "GET",
            "PUT"
          ]
        }
      },
      "methods": {
        "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nbtrJKKA9m45a0g4/methods",
        "hints": {
          "allow": [
            "GET"
          ]
        }
      }
    }
  },
  {
    "type": "phone",
    "id": "aut1nbuyD8m1ckAYc0g4",
    "key": "phone_number",
    "status": "INACTIVE",
    "name": "Phone",
    "created": "2020-07-26T21:05:23.000Z",
    "lastUpdated": "2020-07-29T00:21:29.000Z",
    "settings": {
            "allowedFor": "none"
     },
    "_links": {
      "self": {
        "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nbuyD8m1ckAYc0g4",
        "hints": {
          "allow": [
            "GET",
            "PUT"
          ]
        }
      },
      "methods": {
        "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nbuyD8m1ckAYc0g4/methods",
        "hints": {
          "allow": [
            "GET"
          ]
        }
      },
      "activate": {
        "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nbuyD8m1ckAYc0g4/lifecycle/activate",
        "hints": {
          "allow": [
            "POST"
          ]
        }
      }
    }
  },
  {
    "type": "security_key",
    "id": "aut1nd8PQhGcQtSxB0g4",
    "key": "webauthn",
    "status": "ACTIVE",
    "name": "Security Key or Biometric",
    "created": "2020-07-26T21:16:37.000Z",
    "lastUpdated": "2020-07-27T18:59:30.000Z",
    "_links": {
      "self": {
        "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nd8PQhGcQtSxB0g4",
        "hints": {
          "allow": [
            "GET",
            "PUT"
          ]
        }
      },
      "methods": {
        "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nd8PQhGcQtSxB0g4/methods",
        "hints": {
          "allow": [
            "GET"
          ]
        }
      },
      "deactivate": {
        "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nd8PQhGcQtSxB0g4/lifecycle/deactivate",
        "hints": {
          "allow": [
            "POST"
          ]
        }
      }
    }
  },
  {
    "type": "security_question",
    "id": "aut1nbvIgEenhwE6c0g4",
    "key": "security_question",
    "status": "ACTIVE",
    "name": "Security Question",
    "created": "2020-07-26T21:05:23.000Z",
    "lastUpdated": "2020-07-26T21:05:23.000Z",
    "_links": {
      "self": {
        "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nbvIgEenhwE6c0g4",
        "hints": {
          "allow": [
            "GET"
          ]
        }
      },
      "methods": {
        "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nbvIgEenhwE6c0g4/methods",
        "hints": {
          "allow": [
            "GET"
          ]
        }
      },
      "deactivate": {
        "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nbvIgEenhwE6c0g4/lifecycle/deactivate",
        "hints": {
          "allow": [
            "POST"
          ]
        }
      }
    }
  }
]

Get an Authenticator by ID

GET /api/v1/authenticators/${authenticatorId}

Fetches an Authenticator by its id

Request path parameters

Parameter	Type	Description
authenticatorId	String	The Authenticator's unique identifier

Request query parameters

N/A

Request body

N/A

Response body

The requested Authenticator

Use example

Returns the Authenticator with an id value of aut1nd8PQhGcQtSxB0g4:

Request

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/authenticators/aut1nd8PQhGcQtSxB0g4"

Response

{
    "type": "security_key",
    "id": "aut1nd8PQhGcQtSxB0g4",
    "key": "webauthn",
    "status": "ACTIVE",
    "name": "Security Key or Biometric",
    "created": "2020-07-26T21:16:37.000Z",
    "lastUpdated": "2020-07-27T18:59:30.000Z",
    "_links": {
        "self": {
            "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nd8PQhGcQtSxB0g4",
            "hints": {
                "allow": [
                    "GET",
                    "PUT"
                ]
            }
        },
        "methods": {
            "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nd8PQhGcQtSxB0g4/methods",
            "hints": {
                "allow": [
                    "GET"
                ]
            }
        },
        "deactivate": {
            "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nd8PQhGcQtSxB0g4/lifecycle/deactivate",
            "hints": {
                "allow": [
                    "POST"
                ]
            }
        }
    }
}

Update Authenticator settings

PUT /api/v1/authenticators/${authenticatorId}

Updates settings on an Authenticator

Request path parameters

Parameter	Type	Description
authenticatorId	String	The Authenticator's unique identifier

Request body

An Authenticator Object

The name attribute is required, settings object is optional and has values based on Authenticator key.

Response body

The updated Authenticator

Use example

Returns the updated Authenticator with an id value of aut1eyvv8siH9G6qw1d7:

Request

curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "name": "Phone",
  "settings": {
    "allowedFor": "recovery"
  }
}' "https://${yourOktaDomain}/api/v1/authenticators/aut1eyvv8siH9G6qw1d7"

Response

{
    "type": "phone",
    "id": "aut1eyvv8siH9G6qw1d7",
    "key": "phone_number",
    "status": "ACTIVE",
    "name": "Phone",
    "created": "2021-09-23T21:11:22.000Z",
    "lastUpdated": "2021-10-19T20:57:27.000Z",
    "settings": {
        "allowedFor": "recovery"
    },
    "_links": {
        "self": {
            "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1eyvv8siH9G6qw1d7",
            "hints": {
                "allow": [
                    "GET",
                    "PUT"
                ]
            }
        },
        "deactivate": {
            "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1eyvv8siH9G6qw1d7/lifecycle/deactivate",
            "hints": {
                "allow": [
                    "POST"
                ]
            }
        },
        "methods": {
            "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1eyvv8siH9G6qw1d7/methods",
            "hints": {
                "allow": [
                    "GET"
                ]
            }
        }
    }
}

Activate an Authenticator

POST /api/v1/authenticators/${authenticatorId}/lifecycle/activate

Activates an Authenticator

Request path parameters

Parameter	Type	Description
authenticatorId	String	The Authenticator's unique identifier

Response body

Returns an Authenticator

Use example

Sets the status of the specified Authenticator to ACTIVE

Request

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/authenticators/aut1nd8PQhGcQtSxB0g4/lifecycle/activate"

Response

{
    "type": "security_key",
    "id": "aut1nd8PQhGcQtSxB0g4",
    "key": "webauthn",
    "status": "ACTIVE",
    "name": "Security Key or Biometric",
    "created": "2020-07-26T21:16:37.000Z",
    "lastUpdated": "2020-07-26T21:59:33.000Z",
    "_links": {
        "self": {
            "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nd8PQhGcQtSxB0g4",
            "hints": {
                "allow": [
                    "GET",
                    "PUT"
                ]
            }
        },
        "methods": {
            "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nd8PQhGcQtSxB0g4/methods",
            "hints": {
                "allow": [
                    "GET"
                ]
            }
        },
        "deactivate": {
            "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nd8PQhGcQtSxB0g4/lifecycle/deactivate",
            "hints": {
                "allow": [
                    "POST"
                ]
            }
        }
    }
}

Deactivate an Authenticator

POST /api/v1/authenticators/${authenticatorId}/lifecycle/deactivate

Deactivates an Authenticator

Request path parameters

Parameter	Type	Description
authenticatorId	String	The Authenticator's unique identifier

Request query parameters

N/A

Request body

N/A

Response body

Returns an Authenticator.

Use example

Sets the status of the specified Authenticator to INACTIVE

Request

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/authenticators/aut1nd8PQhGcQtSxB0g4/lifecycle/deactivate"

Response

{
    "type": "security_key",
    "id": "aut1nd8PQhGcQtSxB0g4",
    "key": "webauthn",
    "status": "INACTIVE",
    "name": "Security Key or Biometric",
    "created": "2020-07-26T21:16:37.000Z",
    "lastUpdated": "2020-07-26T22:01:46.000Z",
    "_links": {
        "self": {
            "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nd8PQhGcQtSxB0g4",
            "hints": {
                "allow": [
                    "GET",
                    "PUT"
                ]
            }
        },
        "methods": {
            "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nd8PQhGcQtSxB0g4/methods",
            "hints": {
                "allow": [
                    "GET"
                ]
            }
        },
        "activate": {
            "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nd8PQhGcQtSxB0g4/lifecycle/activate",
            "hints": {
                "allow": [
                    "POST"
                ]
            }
        }
    }
}

Error response example

If the Authenticator that you are trying to deactivate is currently in use as part of an active policy, you receive a 403 error:

{
    "errorCode": "E0000148",
    "errorSummary": "Cannot disable this authenticator because it is enabled in one or more policies. To continue, disable the authenticator in these policies.",
    "errorLink": "E0000148",
    "errorId": "oae2VGZs7HVR6CuUdwmtkE-Ig",
    "errorCauses": [
        {
            "errorSummary": "Self-Service Password Management Policies: Legacy Policy, Default Policy"
        },
        {
            "errorSummary": "Authenticator Enrollment Policies: Default Policy"
        }
    ]
}

List all Methods of an Authenticator

GET /api/v1/authenticators/${authenticatorId}/methods

Lists all Methods of an Authenticator identified by authenticatorId

Request path parameters

Parameter	Type	Description
authenticatorId	String	The Authenticator's unique identifier

Response body

An array of Authenticator Method objects

Retrieve an Authenticator Method

GET /api/v1/authenticators/${authenticatorId}/methods/${methodType}

Retrieves an Authenticator Method identified by authenticatorId and methodType

Request path parameters

Parameter	Type	Description
authenticatorId	String	The Authenticator's unique identifier
methodType	String (Enum)	The type of authenticator method. Possible values: cert, duo, email, idp, otp, password, push, security_question, signed_nonce, sms, totp, voice, or webauthn

Response body

An Authenticator Method object

Replace an Authenticator Method

PUT /api/v1/authenticators/${authenticatorId}/methods/${methodType}

Replaces the properties of an Authenticator Method identified by authenticatorId and methodType

Request path parameters

Parameter	Type	Description
authenticatorId	String	The Authenticator's unique identifier
methodType	String (Enum)	The type of authenticator method. Possible values: cert, duo, email, idp, otp, password, push, security_question, signed_nonce, sms, totp, voice, or webauthn

Request body

Property	Type	Description
status	String (Enum)	The status of the authenticator method. Possible values: ACTIVE or INACTIVE
type	String (Enum)	The type of authenticator method. Possible values: cert, duo, email, idp, otp, password, push, security_question, signed_nonce, sms, totp, voice, or webauthn

Response body

Returns an updated Authenticator Method object

Activate an Authenticator Method

POST /api/v1/authenticators/${authenticatorId}/methods/${methodType}/lifecycle/activate

Activates an Authenticator Method identified by authenticatorId and methodType

Request path parameters

Parameter	Type	Description
authenticatorId	String	The Authenticator's unique identifier
methodType	String (Enum)	The type of authenticator method. Possible values: cert, duo, email, idp, otp, password, push, security_question, signed_nonce, sms, totp, voice, or webauthn

Response body

An Authenticator Method object

Deactivate an Authenticator Method

POST /api/v1/authenticators/${authenticatorId}/methods/{methodType}/lifecycle/deactivate

Deactivates an Authenticator Method identified by authenticatorId and methodType

Request path parameters

Parameter	Type	Description
authenticatorId	String	The Authenticator's unique identifier
methodType	String (Enum)	The type of authenticator method. Possible values: cert, duo, email, idp, otp, password, push, security_question, signed_nonce, sms, totp, voice, or webauthn

Response body

An Authenticator Method object

Authenticators Administration API objects

Authenticator object

Authenticator properties

Property	Type	Description	Applies to Authenticator Key
_links	JSON HAL (opens new window)	Link relations for this object	All Authenticators
created	String (ISO-8601)	Timestamp when the Authenticator was created	All Authenticators
id	String	A unique identifier for the Authenticator	All Authenticators
key	String	A human-readable string that identifies the Authenticator. Values include: custom_app, duo, okta_email, google_otp, external_idp, okta_password, okta_verify, onprem_mfa, phone_number, security_key, security_question, symantec_vip, smart_card_idp, webauthn, or yubikey_token	All Authenticators
status	ACTIVE,INACTIVE	Status of the Authenticator	All Authenticators
lastUpdated	String (ISO-8601)	Timestamp when the Authenticator was last modified	All Authenticators
name	String	Display name of the Authenticator	All Authenticators
type	String (Enum)	The type of Authenticator. Values include: password, security_question, phone, email, app, federated, and security_key.	All Authenticators
settings.allowedFor	String (Enum)	The allowed types of uses for the Authenticator. Values include: recovery, sso, any, and none.	okta_email, phone_number, security_question
settings.tokenLifetimeInMinutes	Number	Specifies the lifetime of an email token and only applies to the email Authenticator type. Default value is 5 minutes.	okta_email
settings.compliance.fips	String (Enum)	REQUIRED, OPTIONAL	okta_verify
settings.channelBinding.style	String	NUMBER_CHALLENGE	okta_verify
settings.channelBinding.required	String (Enum)	NEVER, ALWAYS, HIGH_RISK_ONLY	okta_verify
settings.userVerification	String (Enum)	REQUIRED, PREFERRED	okta_verify, custom_app
settings.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.	okta_verify, custom_app
provider.type	String	Provider type. Supported value for Duo: DUO. Supported value for Custom App: PUSH	duo and other authenticators making use of the provider object
provider.configuration.host	String	The Duo Security API hostname	duo
provider.configuration.integrationKey	String	The Duo Security integration key	duo
provider.configuration.secretKey	String	The Duo Security secret key	duo
provider.configuration.userNameTemplate.template	String	The Duo Security user template name	duo
agreeToTerms	Boolean	A value of true indicates that the administrator accepts the terms (opens new window) 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.	custom_app
provider.configuration.apns.id	String	ID of the APNs (Apple Push Notification Service) configuration	custom_app
provider.configuration.apns.id	String	AppBundleId for the APNs (Apple Push Notification Service) configuration	custom_app
provider.configuration.apns.id	String	DebugAppBundleId for the APNs (Apple Push Notification Service) configuration	custom_app
provider.configuration.fcm.id	String	ID of the FCM (Firebase Cloud Messaging Service) configuration	custom_app

Example Email Authenticator

{
  "type": "email",
  "id": "aut1nbsPHh7jNjjyP0g4",
  "key": "okta_email",
  "status": "ACTIVE",
  "name": "Email",
  "created": "2020-07-26T21:05:23.000Z",
  "lastUpdated": "2020-07-28T21:45:52.000Z",
  "settings": {
            "allowedFor": "recovery",
            "tokenLifetimeInMinutes": 5
   },
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nbsPHh7jNjjyP0g4",
      "hints": {
        "allow": [
          "GET",
          "PUT"
        ]
      }
    },
    "methods": {
      "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nbsPHh7jNjjyP0g4/methods",
      "hints": {
        "allow": [
          "GET"
        ]
      }
    },
    "deactivate": {
      "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nbsPHh7jNjjyP0g4/lifecycle/deactivate",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

Example Password Authenticator

{
  "type": "password",
  "id": "aut1nbtrJKKA9m45a0g4",
  "key": "okta_password",
  "status": "ACTIVE",
  "name": "Password",
  "created": "2020-07-26T21:05:23.000Z",
  "lastUpdated": "2020-07-26T21:05:23.000Z",
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nbtrJKKA9m45a0g4",
      "hints": {
        "allow": [
          "GET",
          "PUT"
        ]
      }
    },
    "methods": {
      "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nbtrJKKA9m45a0g4/methods",
      "hints": {
        "allow": [
          "GET"
        ]
      }
    }
  }
}

Example Phone Authenticator

{
  "type": "phone",
  "id": "aut1nbuyD8m1ckAYc0g4",
  "key": "phone_number",
  "status": "ACTIVE",
  "name": "Phone",
  "created": "2020-07-26T21:05:23.000Z",
  "lastUpdated": "2020-07-29T00:21:29.000Z",
  "settings": {
            "allowedFor": "sso"
  },
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nbuyD8m1ckAYc0g4",
      "hints": {
        "allow": [
          "GET",
          "PUT"
        ]
      }
    },
    "methods": {
      "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nbuyD8m1ckAYc0g4/methods",
      "hints": {
        "allow": [
          "GET"
        ]
      }
    },
    "activate": {
      "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nbuyD8m1ckAYc0g4/lifecycle/deactivate",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

Example Security Question Authenticator

{
  "type": "security_question",
  "id": "aut1nbvIgEenhwE6c0g4",
  "key": "security_question",
  "status": "ACTIVE",
  "name": "Security Question",
  "created": "2020-07-26T21:05:23.000Z",
  "lastUpdated": "2020-07-26T21:05:23.000Z",
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nbvIgEenhwE6c0g4",
      "hints": {
        "allow": [
          "GET"
        ]
      }
    },
    "methods": {
      "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nbvIgEenhwE6c0g4/methods",
      "hints": {
        "allow": [
          "GET"
        ]
      }
    },
    "deactivate": {
      "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nbvIgEenhwE6c0g4/lifecycle/deactivate",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

Example WebAuthn Authenticator

{
  "type": "security_key",
  "id": "aut1nd8PQhGcQtSxB0g4",
  "key": "webauthn",
  "status": "ACTIVE",
  "name": "Security Key or Biometric",
  "created": "2020-07-26T21:16:37.000Z",
  "lastUpdated": "2020-07-27T18:59:30.000Z",
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nd8PQhGcQtSxB0g4",
      "hints": {
        "allow": [
          "GET",
          "PUT"
        ]
      }
    },
    "methods": {
      "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nd8PQhGcQtSxB0g4/methods",
      "hints": {
        "allow": [
          "GET"
        ]
      }
    },
    "deactivate": {
      "href": "https://{yourOktaDomain}/api/v1/authenticators/aut1nd8PQhGcQtSxB0g4/lifecycle/deactivate",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

Example Duo Authenticator

{
    "type": "app",
    "id": "aut5gnvcjUHIWb25J0g4",
    "key": "duo",
    "status": "ACTIVE",
    "name": "Duo Security",
    "created": "2022-07-15T21:14:02.000Z",
    "lastUpdated": "2022-07-15T21:14:02.000Z",
    "settings": {},
    "provider": {
        "type": "DUO",
        "configuration": {
            "host": "https://api-xxxxxxxx.duosecurity.com",
            "userNameTemplate": {
                "template": "oktaId"
            }
        }
    },
    "_links": {
        "self": {
            "href": "https://{yourOktaDomain}/api/v1/authenticators/aut5gnvcjUHIWb25J0g4",
            "hints": {
                "allow": [
                    "GET",
                    "PUT"
                ]
            }
        },
        "deactivate": {
            "href": "https://{yourOktaDomain}/api/v1/authenticators/aut5gnvcjUHIWb25J0g4/lifecycle/deactivate",
            "hints": {
                "allow": [
                    "POST"
                ]
            }
        },
        "methods": {
            "href": "https://{yourOktaDomain}/api/v1/authenticators/aut5gnvcjUHIWb25J0g4/methods",
            "hints": {
                "allow": [
                    "GET"
                ]
            }
        }
    }
}

Example Custom App Authenticator Early Access

{
    "type": "app",
    "id": "aut67ryPSDvEpomfS0g5",
    "key": "custom_app",
    "status": "ACTIVE",
    "name": "Custom App Authenticator",
    "created": "2022-06-24T21:02:50.000Z",
    "lastUpdated": "2022-06-24T21:02:50.000Z",
    "settings": {
        "appInstanceId": "0oa33z6AFuYWYjdBf0g4",
        "userVerification": "PREFERRED",
        "oauthClientId": "myCustomAppClientId"
    },
    "provider": {
        "type": "PUSH",
        "configuration": {
            "apns": {
                "id": "ppc1buciB5V7ZdcB70g4",
                "appBundleId":"com.my.app.release",
                "debugAppBundleId":"com.my.app.debug"
            },
            "fcm": {
                "id": "ppc38rxEr5dEKqDD10g4"
            }
        }
    },
    "_links": {
        "self": {
            "href": "https://{yourOktaDomain}/api/v1/authenticators/aut36ryPSDvEpomfS0g4",
            "hints": {
                "allow": [
                    "GET",
                    "PUT"
                ]
            }
        },
        "deactivate": {
            "href": "https://{yourOktaDomain}/api/v1/authenticators/aut36ryPSDvEpomfS0g4/lifecycle/deactivate",
            "hints": {
                "allow": [
                    "POST"
                ]
            }
        },
        "methods": {
            "href": "https://{yourOktaDomain}/api/v1/authenticators/aut36ryPSDvEpomfS0g4/methods",
            "hints": {
                "allow": [
                    "GET"
                ]
            }
        }
    }
}

Example Smart Card Authenticator

{
  "type": "federated",
  "id": "aut4dkon7d3YCnOMg0g7",
  "key": "smart_card_idp",
  "status": "ACTIVE",
  "name": "Smart Card IdP",
  "created": "2023-02-02T21:47:49.000Z",
  "lastUpdated": "2023-02-02T21:47:49.000Z",
  "provider": {
    "type": "SMART_CARD",
    "configuration": {
      "idpIds": [
        "0oa4ct36utYyaAK8k0g7"
      ]
    }
  },
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/authenticators/aut4dkon7d3YCnOMg0g7",
      "hints": {
        "allow": [
          "GET",
          "PUT"
        ]
      }
    },
    "deactivate": {
      "href": "https://{yourOktaDomain}/api/v1/authenticators/aut4dkon7d3YCnOMg0g7/lifecycle/deactivate",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "methods": {
      "href": "https://{yourOktaDomain}/api/v1/authenticators/aut4dkon7d3YCnOMg0g7/methods",
      "hints": {
        "allow": [
          "GET"
        ]
      }
    }
  }
}

Authenticator Method object

Authenticator Method properties

Property	Type	Description	Applies to Authenticator Method type
_links	JSON HAL (opens new window)	Link relations for this Authenticator Method object	All Authenticator Methods
settings	Authenticator Method Settings object	Specific settings for the authenticator method	otp, push, signed_nonce, totp, webauthn
status	String (Enum)	The status of the authenticator method. Possible values: ACTIVE or INACTIVE	All Authenticator Methods
type	String (Enum)	The type of authenticator method. Possible values: cert, duo, email, idp, otp, password, push, security_question, signed_nonce, sms, totp, voice, or webauthn	All Authenticator Methods

Authenticator Method Settings object

Authenticator Method Settings properties

Note: The aaguidGroups property 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.

Property	Type	Description	Applies to Authenticator Method type
aaguidGroups Early Access	Array of AAGUID Group	The FIDO2 AAGUID groups available to the WebAuthn authenticator.	webauthn
acceptableAdjacentIntervals	Integer	The number of acceptable adjacent intervals, also known as the clock drift interval. This setting allows you to build in tolerance for any time difference between the token and the server. For example, with a timeIntervalInSeconds of 60 seconds and an acceptableAdjacentIntervals value of 5, Okta accepts passcodes within 300 seconds (60 * 5) before or after the end user enters their code. Possible values: 0–10	otp
algorithms	String (Enum)	Algorithms supported. Possible values: RS256, ES256, HMACSHA1, HMACSHA256, or HMACSHA512	otp, totp, push, signed_nonce
attachment	String (Enum)	Method attachment. Possible values: ANY, BUILT_IN, or ROAMING	webauthn
encoding	String (Enum)	The shared secret encoding. Possible values: Base32, Base64, or Hexadecimal	otp, totp
keyProtection	String (Enum)	Indicates whether you must use a hardware key store for push and signed_nonce methods or if any type of key store is allowed. Supported values: ANY or HARDWARE	push, signed_nonce
passCodeLength	Integer	Number of digits in an OTP value	otp, totp
protocol	String (Enum)	The protocol used. Possible values: SYMANTEC,TOTP, or YUBICO	otp
showSignInWithOV	String (Enum)	Controls whether to show the Sign in with Okta Verify button on the Sign-In Widget for the signed_nonce method. Possible Values: ALWAYS or NEVER	signed_nonce
timeIntervalInSeconds	Integer	Time interval for TOTP in seconds	otp, totp
userVerification	String (Enum)	User verification setting. See User Verification (opens new window). Possible values: DISCOURAGED (the authenticator isn't asked to perform user verification, but may do so at its discretion), PREFERRED (the client uses an authenticator capable of user verification if possible), or REQUIRED(the client uses only an authenticator capable of user verification)	webauthn

AAGUID Group object

Early Access

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.

AAGUID Group properties

Property	Type	Description
aaguids	Array of string	A list of YubiKey hardware FIDO2 Authenticator Attestation Global Unique Identifiers (AAGUIDs). The available AAGUIDs (opens new window) are provided by the FIDO Alliance Metadata Service.
name	String	A name to identify the group of YubiKey hardware FIDO2 AAGUIDs

Authenticator Method examples

okta_verify Authenticator Methods example

[
  {
    "type": "totp",
    "status": "ACTIVE",
    "settings": {
      "timeIntervalInSeconds": 30,
      "encoding": "Base32",
      "algorithm": "HMACSHA1",
      "passCodeLength": 6
    },
    "_links": {
      "self": {
        "href": "https://{yourDomain}/api/v1/authenticators/{authenticatorId}/methods/totp",
        "hints": {
          "allow": [
            "GET",
            "PUT"
          ]
        }
      }
    }
  },
  {
    "type": "push",
    "status": "ACTIVE",
    "settings": {
      "algorithms": [
        "RS256",
        "ES256"
      ],
      "keyProtection": "ANY"
    },
    "_links": {
      "self": {
        "href": "https://{yourDomain}/api/v1/authenticators/{authenticatorId}/methods/push",
        "hints": {
          "allow": [
            "GET",
            "PUT"
          ]
        }
      },
      "deactivate": {
        "href": "https://{yourDomain}/api/v1/authenticators/{authenticatorId}/methods/push/lifecycle/deactivate",
        "hints": {
          "allow": [
            "POST"
          ]
        }
      }
    }
  },
  {
    "type": "signed_nonce",
    "status": "ACTIVE",
    "settings": {
      "algorithms": [
        "ES256",
        "RS256"
      ],
      "keyProtection": "ANY",
      "showSignInWithOV": "ALWAYS"
    },
    "_links": {
      "self": {
        "href": "https://{yourDomain}/api/v1/authenticators/{authenticatorId}/methods/signed_nonce",
        "hints": {
          "allow": [
            "GET",
            "PUT"
          ]
        }
      },
      "deactivate": {
        "href": "https://{yourDomain}/api/v1/authenticators/{authenticatorId}/methods/signed_nonce/lifecycle/deactivate",
        "hints": {
          "allow": [
            "POST"
          ]
        }
      }
    }
  }
]

okta_email Authenticator Methods example

[
  {
    "type": "email",
    "status": "ACTIVE",
    "_links": {
      "self": {
        "href": "https://{yourDomain}/api/v1/authenticators/{authenticatorId}/methods/email",
        "hints": {
          "allow": [
            "GET",
            "PUT"
          ]
        }
      }
    }
  }
]