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

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

200
403
429

application/json

[{"value": {"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"
]
}
}
}
}
},
{"value": {"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"
]
}
}
}
}
},
{"value": {"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"
]
}
}
}
}
},
{"value": {"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"
]
}
}
}
}
}
]

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

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"

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": {"userNameTemplate": {"template": "oktaId"
},
"integrationKey": "testIntegrationKey",
"secretKey": "testSecretKey",
"host": "https://api-xxxxxxxx.duosecurity.com"
}
}
}

Response samples

200
400
403
429

application/json

{"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"
]
}
}
}
}

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

200
403
404
429

application/json

{"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"
]
}
}
}
}

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

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"

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": {"userNameTemplate": {"template": "oktaId"
},
"integrationKey": "testIntegrationKey",
"secretKey": "testSecretKey",
"host": "https://api-xxxxxxxx.duosecurity.com"
}
}
}

Response samples

200
400
403
404
429

application/json

{"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"
]
}
}
}
}

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

200
403
404
429

application/json

{"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"
]
}
}
}
}

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

200
403
404
429

application/json

{"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 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

200
403
404
429

application/json

[{"status": "ACTIVE",
"type": "cert",
"_links": {"self": {"hints": {"allow": ["DELETE"
]
},
"href": "string",
"name": "string",
"type": "string"
},
"activate": {"hints": {"allow": ["DELETE"
]
},
"href": "string",
"name": "string",
"type": "string"
},
"deactivate": {"hints": {"allow": ["DELETE"
]
},
"href": "string",
"name": "string",
"type": "string"
}
}
}
]

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

200
403
404
429

application/json

{"status": "ACTIVE",
"type": "sms",
"_links": {"self": {"hints": {"allow": ["DELETE"
]
},
"href": "string",
"name": "string",
"type": "string"
},
"activate": {"hints": {"allow": ["DELETE"
]
},
"href": "string",
"name": "string",
"type": "string"
},
"deactivate": {"hints": {"allow": ["DELETE"
]
},
"href": "string",
"name": "string",
"type": "string"
}
}
}

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) sms

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

200
400
403
404
429

application/json

{"status": "ACTIVE",
"type": "sms",
"_links": {"self": {"hints": {"allow": ["DELETE"
]
},
"href": "string",
"name": "string",
"type": "string"
},
"activate": {"hints": {"allow": ["DELETE"
]
},
"href": "string",
"name": "string",
"type": "string"
},
"deactivate": {"hints": {"allow": ["DELETE"
]
},
"href": "string",
"name": "string",
"type": "string"
}
}
}

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

200
403
404
429

application/json

{"status": "ACTIVE",
"type": "sms",
"_links": {"self": {"hints": {"allow": ["DELETE"
]
},
"href": "string",
"name": "string",
"type": "string"
},
"activate": {"hints": {"allow": ["DELETE"
]
},
"href": "string",
"name": "string",
"type": "string"
},
"deactivate": {"hints": {"allow": ["DELETE"
]
},
"href": "string",
"name": "string",
"type": "string"
}
}
}

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

200
403
404
429

application/json

{"status": "ACTIVE",
"type": "sms",
"_links": {"self": {"hints": {"allow": ["DELETE"
]
},
"href": "string",
"name": "string",
"type": "string"
},
"activate": {"hints": {"allow": ["DELETE"
]
},
"href": "string",
"name": "string",
"type": "string"
},
"deactivate": {"hints": {"allow": ["DELETE"
]
},
"href": "string",
"name": "string",
"type": "string"
}
}
}

Authenticators

List all AuthenticatorsIdentity EngineOAuth 2.0: okta.authenticators.read

Create an AuthenticatorIdentity EngineOAuth 2.0: okta.authenticators.manage

query Parameters

Request Body schema: application/json

Retrieve an AuthenticatorIdentity EngineOAuth 2.0: okta.authenticators.read

path Parameters

Replace an AuthenticatorIdentity EngineOAuth 2.0: okta.authenticators.manage

path Parameters

Request Body schema: application/json

Activate an AuthenticatorIdentity EngineOAuth 2.0: okta.authenticators.manage

path Parameters

Deactivate an AuthenticatorIdentity EngineOAuth 2.0: okta.authenticators.manage

path Parameters

List all Methods of an AuthenticatorIdentity EngineOAuth 2.0: okta.authenticators.read

path Parameters

Retrieve a MethodIdentity EngineOAuth 2.0: okta.authenticators.read

path Parameters

Replace a MethodIdentity EngineOAuth 2.0: okta.authenticators.manage

path Parameters

Request Body schema: application/json

Activate an Authenticator MethodIdentity EngineOAuth 2.0: okta.authenticators.manage

path Parameters

Deactivate an Authenticator MethodIdentity EngineOAuth 2.0: okta.authenticators.manage

path Parameters

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

Create an Authenticator
Identity Engine
OAuth 2.0: `okta.authenticators.manage`

Retrieve an Authenticator
Identity Engine
OAuth 2.0: `okta.authenticators.read`

Replace an Authenticator
Identity Engine
OAuth 2.0: `okta.authenticators.manage`

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

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

List all Methods of an Authenticator
Identity Engine
OAuth 2.0: `okta.authenticators.read`

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

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

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

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