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

Create an app authenticator enrollment
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
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
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
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"
    }
]