PingOne Platform APIs

MFA Authentication Code

The /authenticationCodes endpoint provides operations to create, read, and delete an authentication code. The authentication code (which can be a QR code) enables users to sign on without any data entry, such as providing a username, password, or entering a one-time passcode. The user scans the code, and if successful, gains access to an application’s services.

Authentication codes request data model

Property Type Required Mutable Description

application.id

String

Required

Mutable

The ID of a mobile application for which the code is valid; only the specified mobile application can scan the QR code.

clientContext

String

Optional

Mutable

An ObjectNode that provides relevant information to the mobile application that can be shown to application users. For example, Do you want to approve this transaction?. For more information, refer to Create Authentication Code.

lifeTime.duration

Integer

Optional

Mutable

The length of time for this authentication code to be valid. The minimum value is 10 seconds; the maximum value is 30 minutes; the default is 1 minute. If the lifeTime.duration property is set, a value for lifeTime.timeUnit is required.

lifeTime.timeUnit

String

Optional

Mutable

The time unit for the lifeTime.duration property. Options are SECONDS and MINUTES. If the lifeTime.timeUnit property is set, a value for lifeTime.duration is required.

userApproval

String

Optional

Mutable

Whether the mobile device must verify that the user approves the authentication with the scanned code. Options are REQUIRED and NOT_REQUIRED.

Authentication codes response data model

Property Type Required Mutable Description

code

String

N/A

Read-only

The authentication code. The code is eight characters in length, and it can include numbers and uppercase letters.

createdAt

Date

N/A

Read-only

When the resource was created.

environment.id

String

N/A

Read-only

The environment’s unique identifier.

expiresAt

Date

N/A

Read-only

The expiration time of authentication code.

id

String

N/A

Read-only

The resource’s unique identifier.

status

String

N/A

Read-only

The status of the authentication code. Options are UNCLAIMED, CLAIMED, EXPIRED, DENIED, and COMPLETED. The EXPIRED status is active for 5 minutes after the code is no longer valid.

updatedAt

Date

N/A

Read-only

When the resource was last updated.

uri

String

N/A

Read-only

A universal link (for example, https://www.example.com/pingonesdk?authentication_code={{generated token}}). This property can also set a link to a schema application (for example, pingoneapp://pingonesdk?authentication_code={{generated token}}). If a universal link or schema application link is not set, the response does not include the pingonesdk?authentication_code={{generated token}} portion of the URL.

user.id

UUID

N/A

Read-only

The unique identifier of the authenticated user.

_embedded.device.otpStatus.status

String

N/A

Read-only

Whether or not the device can be used currently for OTP-based authentication. Value returned is ENABLED or DISABLED. Relevant only for devices where type is MOBILE.

_embedded.device.otpStatus.reason

String

N/A

Read-only

If the status is DISABLED, contains the reason that the device cannot be used for OTP-based authentication, for example, that the application used a version of the MFA SDK that does not support OTP. Relevant only for devices where type is MOBILE.

_embedded.device.pushStatus.status

String

N/A

Read-only

Whether or not the device can be used currently for push-based authentication. Value returned is ENABLED or DISABLED. Relevant only for devices where type is MOBILE.

_embedded.device.pushStatus.reason

String

N/A

Read-only

If the status is DISABLED, contains the reason that the device cannot be used for push-based authentication, for example, that the push option was disabled for the application in the MFA policy. Relevant only for devices where type is MOBILE.

_embedded.device.usableStatus.status

String

N/A

Read-only

Whether or not the device can be used currently for authentication. Value returned is ENABLED or DISABLED.

_embedded.device.usableStatus.reason

String

N/A

Read-only

If the status is DISABLED, contains the reason that the device cannot be used for authentication, for example, that the defined daily notifications limit has already been reached.

For descriptions of other fields under _embedded.device, refer to MFA Devices.

For descriptions of fields under _embedded.user, refer to Users data model.

Authentication codes errors

In addition to the general error codes, authenticationCodes operations can return the following errors:

HTTP status Top‑level code Detail code When it happens and what the response contains

400

INVALID_DATA

EMPTY_VALUE or INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A create request references an application that does not exist or is not a mobile application, an approve request omits user when userApproval is not DENY, omits userApproval when the code requires it, or supplies a code that does not match the code being approved

Details: application id=<applicationId> not found or The configured application id <applicationId> not a mobile application with target application.id, must not be null with target user (detail EMPTY_VALUE), userApproval not provided. code=<code> with target userApproval, The provided code=<code> didn’t match to the provided authentication code id <id>., The provided user=<userId> didn’t match to the relevant device. code=<code> with target user.id, or The provided device didn’t match to the device that claim the authentication code. code=<code>

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A claim request targets a code whose current status is not UNCLAIMED, or an approve request targets a code whose current status is not CLAIMED

Details: The code <code>, is already claimed. The current status is CLAIMED with target code, or Invalid State. The current status of the authentication code is <status>. code=<code>

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A claim request supplies device identity fields (fnp, iss, or universalTrustJwt) that match devices, but none belongs to the code’s application

Details: The provided device application id doesn’t match the request. applicationId=<applicationId> code=<code>

403

ACCESS_FAILED

None

Message: The actor attempting to perform the request is not authorized.

When and details

When: The actor lacks the mfa:authenticate:device permission for the create, read, or delete operations

Details: None

404

NOT_FOUND

None

Message: The request could not be completed. The requested resource was not found.

When and details

When: A read or delete operation references an authentication code that does not exist, or a claim request supplies device identity fields that do not match any device

Details: For the claim case, Device not found for the provided fnp and iss. code=<code> (detail code INVALID_VALUE)

417

INVALID_DATA

None

Message: This mobile device does not comply with policy requirements. Contact support.

When and details

When: A claim or approve request comes from a mobile device that the device integrity evaluation marked as compromised

Details: None

500

UNEXPECTED_ERROR

None

Message: There was an unexpected error with the service. Please try again later.

When and details

When: The service fails internally while generating a unique authentication code or converting the resource

Details: None