App Authenticators

The MyAccount App Authenticators API provides operations to enroll, update, and delete an app authenticator. The API also allows users to view and verify pending notification challenges. The API only supports custom authenticators. See the Custom authenticator integration guide.

API versioning

A valid API version in the Accept header is required to access the API. Current version: 1.0.0

Accept: application/json; okta-version=1.0.0

PushNotificationChallengeRequestJwt

JSON Web Token payload constructed by Okta for the push notification challenge request JWT

appInstanceName
string

Friendly name of the application for the authentication request

aud
string

Audience (maps to the application ID)

authenticatorEnrollmentId
string

ID of the app authenticator enrollment

authorizationServerId
string

ID of the authorization server that signed the challenge request

object
clientOS
string

OS of the client making the request

clientLocation
string

Location of the request

transactionTime
string

Time the challenge request was created

transactionType
string

Indicates if the request is CIBA or LOGIN

Enum: "CIBA" "LOGIN"
bindingMessage
string

If transactionType is CIBA, this message must be shown to the user

exp
string

Expiration time of token (UNIX timestamp)

iat
string

Issuing time of token (UNIX timestamp)

iss
string

Issuer (maps to the org URL)

jti
string

Token ID (matches transactionId)

method
string

Method type requested for the response

Value: "push"
methodEnrollmentId
string

ID of the push method enrollment

nonce
string

Randomly generated nonce value

orgId
string

ID of the organization

signals
Array of arrays

Array of string values describing client signals requested for collection

transactionId
string

Transaction ID (matches the challengeId path parameter)

userId
string

ID of the user being challenged

userMediation
string

Indicates if user mediation is required

Enum: Description
NONE

User interaction isn't required by the client during authentication.

OPTIONAL

The client can decide to interact with the user or not.

REQUIRED

The client must interact with the user. If a biometrics prompt occurs during user verification, additional consent prompt isn't shown by the client.

userVerification
string

Indicates if user verification (biometrics) is used in the response

Enum: Description
NONE

The client doesn't require any user verification as part of the authentication flow.

DISCOURAGED

The client prefers a proof of possession flow without user interaction. However, the client can prompt for user verification if it allows for a better user experience.

PREFERRED

Client user verification prompt is preferred. If the user verification key is unavailable, the client can use the proof of possession. In this situation, Okta recommends that the client send UV_TEMPORARILY_UNAVAILABLE or UV_PERMANENTLY_UNAVAILABLE in the challenge response's userConsent field.

REQUIRED

The client must prompt for user verification and otherwise fail silently without user interaction.

ver
integer

Version of the JWT (supported value: 0)

verificationUri
string

The expected endpoint posted by the client for the challenge response

{
  • "appInstanceName": "string",
  • "aud": "string",
  • "authenticatorEnrollmentId": "pfd7rzcmvlhmE0Y1w0g4",
  • "authorizationServerId": "string",
  • "challengeContext": {
    • "clientOS": "string",
    • "clientLocation": "string",
    • "transactionTime": "string",
    • "transactionType": "CIBA",
    • "bindingMessage": "string"
    },
  • "exp": "string",
  • "iat": "string",
  • "iss": "string",
  • "jti": "string",
  • "method": "push",
  • "methodEnrollmentId": "opf6aeq9U2hoM8aqO0w5",
  • "nonce": "string",
  • "orgId": "string",
  • "signals": [ ],
  • "transactionId": "string",
  • "userId": "string",
  • "userMediation": "REQUIRED",
  • "userVerification": "REQUIRED",
  • "ver": 0,
  • "verificationUri": "string"
}

PushNotificationChallengeRequestJwtHeader

JSON Web Token header used for the push notification challenge request JWT

alg
string

Signing algorithm used

kid
string

Signing key ID that matches the key ID used by the authorization server

typ
string

Type of token

Value: "okta-pushbind+jwt"
{
  • "alg": "RS256",
  • "kid": "“seD0hUMrcpFtlVVTmkDyJ0mGxlEygWEZ42ts9z4ih9M”",
  • "typ": "okta-pushbind+jwt"
}

PushNotificationChallengeResponseJwt

JSON Web Token payload used for the push notification challenge response JWT

aud
required
string

Audience (matches the org URL)

required
object

Object describing the response context

userConsent
required
string

Type of user consent

Enum: Description
NONE

There was no interaction with the end user as part of the authentication

APPROVED_CONSENT_PROMPT

The user approved the consent prompt

APPROVED_USER_VERIFICATION

The user approved the user verification by providing biometrics or a PIN

CANCELLED_USER_VERIFICATION

The user cancelled user verification by rejecting the biometrics prompt

DENIED_CONSENT_PROMPT

The user rejected the consent prompt

UV_TEMPORARILY_UNAVAILABLE

The client currently can't access the user verification key

UV_PERMANENTLY_UNAVAILABLE

The client permanently lost access to the user verification key

USER_ABANDONED

The user cancelled user verification by closing the biometrics prompt

transactionType
string

Type of transaction

Enum: "LOGIN" "CIBA"
object

JSON dictionary with the signals keys (and their values) requested in the challenge request

id
string

ID of the device

isHardwareProtectionEnabled
boolean

Indicates whether the Android device supports a hardware keystore or if the iOS device supports Secure Enclave

model
string

The device type or design

manufacturer
string

The vendor that created the physical device

displayName
string

The display name of the device

platform
string

The device operating system

Enum: "ANDROID" "IOS"
osVersion
string

The device operating system software version

clientInstanceId
string

Key ID of the client instance key

clientInstanceBundleId
string

ID of the application bundle

clientInstanceVersion
string

Application version

secureHardwarePresent
boolean

Indicates if secure hardware is present

screenLockType
string

Screen lock type set on the device

Enum: Description
NONE

No passcode is set on the device

PASSCODE

Only a passcode or password is set on the device (biometrics aren't set up)

BIOMETRIC

Passcode and biometrics are set on the device

diskEncryptionType
string

Disk encryption type of the device profile

Enum: Description
NONE

No encryption has been set

FULL

The disk is fully encrypted

USER

The encryption key is tied to the user or profile (Android only)

exp
required
string

Expiration time of token (UNIX timestamp)

iat
required
string

Issuing time of token (UNIX timestamp)

iss
required
string

Issuer (matches the app authenticator enrollment ID)

jti
required
string

Randomly generated ID for every response

keyType
required
string

Type of key used to sign the JWT

Enum: "proofOfPossession" "userVerification"
methodEnrollmentId
required
string

ID of the push method enrollmnet

nbf
required
string

Token isn't valid before this time (UNIX timestamp)

nonce
required
string

Matches the nonce in the challenge request

sub
required
string

Subject (matches the user ID)

tx
required
string

Matches the transactionId in the challenge request

{
  • "aud": "string",
  • "challengeResponseContext": {
    • "userConsent": "APPROVED_CONSENT_PROMPT",
    • "transactionType": "LOGIN"
    },
  • "deviceSignals": {
    • "id": "string",
    • "isHardwareProtectionEnabled": true,
    • "model": "iPhone",
    • "manufacturer": "Apple",
    • "displayName": "string",
    • "platform": "IOS",
    • "osVersion": "11.4",
    • "clientInstanceId": "string",
    • "clientInstanceBundleId": "string",
    • "clientInstanceVersion": "string",
    • "secureHardwarePresent": true,
    • "screenLockType": "BIOMETRIC",
    • "diskEncryptionType": "FULL"
    },
  • "exp": "string",
  • "iat": "string",
  • "iss": "string",
  • "jti": "string",
  • "keyType": "proofOfPossession",
  • "methodEnrollmentId": "opf6aeq9U2hoM8aqO0w5",
  • "nbf": "string",
  • "nonce": "string",
  • "sub": "string",
  • "tx": "string"
}

PushNotificationChallengeResponseJwtHeader

JSON Web Token header used for the push notification challenge response JWT

alg
required
string

Signing algorithm used

kid
required
string

Signing key ID that matches the key ID used during the authenticator enrolment flow

typ
required
string

Type of token

Value: "okta-pushbind+jwt"
{
  • "alg": "RS256",
  • "kid": "“7fbc27fd-e3df-4522-86bf-1930110256ad”",
  • "typ": "okta-pushbind+jwt"
}

Create an app authenticator enrollment
Identity Engine
OAuth 2.0: okta.myAccount.appAuthenticator.manage

Creates an app authenticator enrollment

Request
Request Body schema: application/json, okta-version=1.0.0
authenticatorId
required
string
required
object
secureHardwarePresent
boolean

Indicates if the device is equipped with TPM storage for storing signing keys

required
KeyEC (object) or KeyRSA (object) (KeyObject)
One of:
crv
required
string
Value: "P-256"
kid
required
string

The unique identifier of the key

kty
required
string

The type of public key

Value: "EC"
okta:kpr
required
string
Enum: "HARDWARE" "SOFTWARE"
x
required
string

The public x coordinate for the elliptic curve point

y
required
string

The public y coordinate for the elliptic curve point

osVersion
required
string
clientInstanceBundleId
required
string
platform
required
string
Enum: "ANDROID" "IOS"
manufacturer
string
deviceAttestation
object
clientInstanceVersion
required
string
clientInstanceDeviceSdkVersion
required
string
model
string
displayName
required
string

The device's display name

udid
string
required
object
required
object
apsEnvironment
string

Target APS type that application registers to. Required for iOS enrollments.

Enum: "PRODUCTION" "DEVELOPMENT"
pushToken
required
string
required
object
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Access Denied

404

Resource Not Found

post/idp/myaccount/app-authenticators
Request samples
application/json, okta-version=1.0.0
{
  • "authenticatorId": "aut12i8bdXk90NIfr0q5",
  • "device": {
    • "secureHardwarePresent": true,
    • "clientInstanceKey": {
      },
    • "osVersion": "14.3",
    • "clientInstanceBundleId": "com.company.authenticatorApp",
    • "platform": "IOS",
    • "manufacturer": "APPLE",
    • "deviceAttestation": { },
    • "clientInstanceVersion": "6.4.0",
    • "clientInstanceDeviceSdkVersion": "DeviceSDK 1.0.0",
    • "model": "iPhone",
    • "displayName": "My device name",
    • "udid": "4956095A-D99E-4A4E-A6DC-9E63E5978722"
    },
  • "methods": {
    • "push": {
      }
    }
}
Response samples
application/json;okta-version=1.0.0
{
  • "authenticatorId": "string",
  • "createdDate": "2019-08-24T14:15:22Z",
  • "device": {
    • "id": "string",
    • "status": "ACTIVE",
    • "createdDate": "2019-08-24T14:15:22Z",
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "clientInstanceId": "string"
    },
  • "id": "string",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "links": {
    • "self": {
      }
    },
  • "methods": {
    • "push": {
      }
    },
  • "user": {
    • "id": "string",
    • "username": "string"
    }
}

Verify a push notification challenge response from the app authenticator

Verifies a push notification challenge from the app authenticator

Request
path Parameters
challengeId
required
string

Id of the challenge associated with the app authenticator

Example: ft-hqOpHM8yxcGvE0cN7UXWVodVyP0omKW
Request Body schema: application/json;okta-version=1.0.0
challengeResponse
string

JWT issued by the app authenticator at the time of push notification verification

This based64-encoded JWT consists of a JWT header and a JWT payload.

method
string
Value: "push"
Responses
200

Verification Success

204

User denied challenge attempt

400

Bad Request

post/idp/myaccount/app-authenticators/challenge/{challengeId}/verify
Request samples
application/json;okta-version=1.0.0
{
  • "method": "push",
  • "challengeResponse": "Your encoded challenge response JWT"
}

Update an app authenticator enrollment
Identity Engine
OAuth 2.0: okta.myAccount.appAuthenticator.maintenance.manage

Updates an app authenticator enrollment

The following update operations are allowed:

  • Update the user verification key
  • Remove the user verification key
  • Update the push token
  • Update the push method transaction types

For more information, see Access token management in the Custom authenticator integration guide.

Note: The following higher risk update operations require a stronger okta.myAccount.appAuthenticator.manage scope:

  • Update the user verification key
  • Remove the user verification key
Request
path Parameters
enrollmentId
required
string

Id of the user's app authenticator enrollment

Example: pfd7rzcmvlhmE0Y1w0g4
Request Body schema: application/merge-patch+json;okta-version=1.0.0
object
object
pushToken
string
object
object (AppAuthenticatorMethodCapabilities)
Responses
200

OK

401

Unauthorized

403

Access Denied

404

Resource Not Found

patch/idp/myaccount/app-authenticators/{enrollmentId}
Request samples
application/merge-patch+json;okta-version=1.0.0
{
  • "methods": {
    • "push": {
      }
    }
}
Response samples
application/json;okta-version=1.0.0
{
  • "authenticatorId": "string",
  • "createdDate": "2019-08-24T14:15:22Z",
  • "device": {
    • "id": "string",
    • "status": "ACTIVE",
    • "createdDate": "2019-08-24T14:15:22Z",
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "clientInstanceId": "string"
    },
  • "id": "string",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "links": {
    • "self": {
      }
    },
  • "methods": {
    • "push": {
      }
    },
  • "user": {
    • "id": "string",
    • "username": "string"
    }
}

Delete an app authenticator enrollment
Identity Engine
OAuth 2.0: okta.myAccount.appAuthenticator.manage

Deletes an app authenticator enrollment

Request
path Parameters
enrollmentId
required
string

Id of the user's app authenticator enrollment

Example: pfd7rzcmvlhmE0Y1w0g4
Responses
204

No Content

401

Unauthorized

403

Access Denied

404

Resource Not Found

delete/idp/myaccount/app-authenticators/{enrollmentId}
Request samples 
Response samples 
application/json;okta-version=1.0.0
{
  • "errorCauses": [
    • {
      }
    ],
  • "errorCode": "E0000001",
  • "errorId": "oaeWGQKoQHeQmy0u8w8bPwi_Q",
  • "errorLink": "E0000001",
  • "errorSummary": "Bad request because XYZ is missing."
}
List all pending push notification challenges
Identity Engine
OAuth 2.0: okta.myAccount.appAuthenticator.maintenance.read
Lists all pending push notification challenges


Request 
path Parameters
enrollmentId
required
string
Id of the user's app authenticator enrollment


 
 Example:  pfd7rzcmvlhmE0Y1w0g4
Responses 
200
Success


401
Unauthorized


get/idp/myaccount/app-authenticators/{enrollmentId}/push/notifications
Request samples 
Response samples 
application/json;okta-version=1.0.0
[
  • {
    • "payloadVersion": "IDXv1",
    • "challenge": "Your encoded challenge request JWT"
    }
]