PingOne Platform APIs

OATH Tokens

You can use the PingOne API for various oath token management actions, including creating tokens, revoking tokens, and resyncing tokens.

The maximum number of OATH tokens you can have in a PingOne environment is 100,000.

Assigning admin roles and permissions to this service

Admin role assignments determine access to PingOne APIs. When assigning admin roles to this service, refer to PingOne Permissions by Service for the service-specific permissions.

You can also choose to assign admin roles based on particular service resources. Refer to PingOne Permissions by Resource when assigning admin roles per service resources.

Admin assignments to roles are set by:

Refer to Roles Management for more information.

== OATH token data model

Property Type Required Mutable Description

createdAt

Date

N/A

Read-only

The date the token was added to the environment.

environment.id

String

N/A

Read-only

The ID of the environment the token is associated with.

hashAlgorithm

String

Optional

Immutable

The algorithm used by the cryptographic hash function to generate OTPs. Can be any of the following values: HmacSHA1, HmacSHA256, HmacSHA512. If not provided, HmacSHA1 is used as the default value. Currently for HOTP tokens, only HmacSHA1 is supported, so this parameter is really only relevant for TOTP tokens.

hotp

Object

Optional

Immutable

Object containing fields that are relevant only for HOTP tokens.

hotp.counter

Integer

Optional

Immutable

The counter used by the HOTP token to generate OTPs. If not provided, 0 is used as the default value.

id

String

N/A

Read-only

The OATH token’s unique identifier.

otpLength

Integer

Required

Immutable

Length of the OTPs generated - can be 6 or 8

rowNumber

Integer

Optional

Immutable

When creating OATH tokens with data that originated in a seed file, rowNumber can be used to indicate the row where the data for the token was located in the file.

secret

String

Required

Immutable

The OATH token’s secret key. Can be up to 200 characters and must be a hexadecimal value. Used only as an input parameter, does not appear in any responses.

serialNumber

String

Required

Immutable

The OATH token’s serial number. Can be up to 50 characters and all characters must be alphanumeric.

totp

Object

Required

Immutable

Object containing fields that are relevant only for TOTP tokens.

totp.drift

Integer

N/A

Read-only

Difference between the token’s time and the server’s time, expressed in time steps. A positive value indicates that the token’s time is ahead.

totp.timeStep

Integer

Required

Immutable

Interval at which the OTP is refreshed - PingOne supports 30 seconds and 60 seconds.

type

String

Required

Immutable

Possible values are HOTP and TOTP.

updatedAt

Date

N/A

Read-only

The date the token was last updated.

_embedded.devices

Array

N/A

Read-only

Array of devices associated with an OATH token.

_embedded.devices.id

String

N/A

Read-only

ID of device associated with an OATH token.

_embedded.devices.userId

String

N/A

Read-only

ID of user for a device associated with an OATH token.

_embedded.oathTokens

Array

N/A

Read-only

Name of the array of tokens returned when all tokens are requested.

OATH token batch creation data model

These properties are relevant only for batch creation of tokens.

Property Type Required Mutable Description

reason

String

N/A

Read-only

If the job status is FAILED, provides the reason for the failure.

result.created

Integer

N/A

Read-only

The number of tokens created.

result.duplicates

Object

N/A

Read-only

Contains information about tokens whose creation was requested but were skipped because they already exist in the environment.

result.duplicates.maskedSecret

String

N/A

Read-only

The secret for the OATH token, partially-hidden.

result.duplicates.rowNumber

Integer

N/A

Read-only

The number of the row where the duplicate token was in the file whose content was imported.

result.duplicates.serialNumber

String

N/A

Read-only

The serial number of the duplicate token.

status

String

N/A

Read-only

The status of the job. Can be PENDING, IN_PROGRESS, FAILED, or DONE.

tokens

Array

Required

Immutable

Name of the array of tokens provided for creation. Each item in the array should include the same information you would include to create a single token, for example, serial number, as described in the OATH token data model table.

type

String

Required

Immutable

The type of job to run. For creation of tokens, set to 'CREATE_OATH_TOKENS'. Should not be confused with the type parameter used within each token in the array provided to indicate the type of token to create - TOTP or HOTP.

OATH token batch revoking data model

These properties are relevant only for batch revoking of tokens.

Property Type Required Mutable Description

forceUnpair

Boolean

Optional

Immutable

By default, revoke jobs revoke only unassigned tokens. Set forceUnpair to true if you want tokens to be revoked even if they are currently associated with a user. The association (device) will be removed before the token is revoked. When forceUnpair is not used, the response includes an array of tokens that were not revoked due to their association with a user.

reason

String

N/A

Read-only

If the job status is FAILED, provides the reason for the failure.

result.revoked

Integer

N/A

Read-only

The number of tokens revoked.

result.unrevoked

Array

N/A

Read-only

Array of objects that contain information about the tokens that were not revoked because they are associated with a user.

result.unrevoked[].devices[].id

String

N/A

Read-only

ID of device associated with the token that was not revoked.

result.unrevoked[].devices[].user.id

String

N/A

Read-only

ID of user whose device is associated with the token that was not revoked.

result.unrevoked[].devices

Array

N/A

Read-only

Array of devices associated with the token that was not revoked.

result.unrevoked[].id

String

N/A

Read-only

ID of the token that was not revoked.

status

String

N/A

Read-only

The status of the job. Can be PENDING, IN_PROGRESS, FAILED, or DONE.

tokenIds

Array

Required

Immutable

Name of the array of tokens provided for revoking. Each element in the array should be the ID of the token to revoke. The maximum number of token IDs you can include in a batch revoke is 1000.

type

String

Required

Immutable

The type of job to run. For revoking of tokens, set to 'REVOKE_OATH_TOKENS'.

OATH token resync data model

These properties are relevant only for resyncing tokens.

Property Type Required Mutable Description

otps

Array

Required

Immutable

Required for resync requests. array of two OTPs for the token, used to calculate the resync. The two OTPs can be provided in a single request or in two separate requests.

OATH tokens errors

In addition to the general error codes, OATH token and OATH job 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: Validation Error : [<property> <message>]

When and details

When: A POST /oathTokens request omits a required property or supplies a value that fails validation

Details: must not be null for an omitted serialNumber or type, must be 6 or 8 for an otpLength other than 6 or 8, totp.timeStep must not be null for a TOTP token without totp.timeStep, timeStep must be 30 or 60 for an unsupported totp.timeStep, drift is not valid for a totp.drift outside the valid range, or invalid value provided for an unrecognized hashAlgorithm, for example Validation Error : [totp.drift drift is not valid]

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: An OATH token operation runs in an environment that does not have the OATH tokens capability enabled

Details: Environment is disabled for OATH_TOKEN with target oath_token.enabled

400

INVALID_DATA

UNIQUENESS_VIOLATION

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

When and details

When: A POST /oathTokens request creates a token with a serial number that already exists in the environment

Details: A resource with the specified name already exists. with target serialNumber and an existingId inner error identifying the existing token

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 resync request supplies no OTP, more than two OTPs, or an OTP that is not 6 or 8 digits

Details: request must contain at least one otp, otps cannot contain more then two passcodes, or otp length must be 6 or 8 digits

400

INVALID_DATA

EXTRA_OTP_REQUIRED

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

When and details

When: An otp.check request for an OATH token device requires another passcode to complete the resync

Details: An extra OTP is required with target otp

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: An otp.check request for an OATH token device supplies a passcode that does not match the token’s next value

Details: Invalid OTP was provided (detail code INVALID_OTP) with target otp and an attemptsRemaining inner error

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request violates a constraint imposed by the service.

When and details

When: A pairing request references an OATH token serial number that does not exist in the environment

Details: OATH Token not found. serialNumber=<serial> with target serialNumber

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request violates a constraint imposed by the service.

When and details

When: A token creation or batch creation request exceeds the environment’s maximum number of OATH tokens (100,000)

Details: The request exceeds the maximum token limit

400

REQUEST_FAILED

None

Message: The request could not be completed. There was an issue processing the request.

When and details

When: An otp.check request targets a token that is locked after too many unsuccessful resync attempts

Details: The token is locked, please try again in a few minutes (detail code TOKEN_LOCKED) with target serialNumber and a lockExpiresAt inner error when a lock expiration is set

400

REQUEST_LIMITED

QUOTA_EXCEEDED

Message: The request will exceed your quota.

When and details

When: Too many unsuccessful resync passcode attempts are made for the token

Details: Too many unsuccessful OTP attempts, please try again in a few minutes with target otp and quotaLimit and coolDownExpiresAt inner errors

403

ACCESS_FAILED

None

Message: The request could not be completed. You do not have access to this resource. for a permission denial, or You do not have permissions or are not licensed to make this request. when the operation is not supported by the environment’s configuration

When and details

When: The actor lacks the mfa:create:oathToken permission (POST), the mfa:read:oathToken permission (GET), the mfa:update:oathToken permission (resync), the mfa:delete:oathToken permission (DELETE), or the mfa:read:oathJob permission (GET /oathJobs), or the operation routes to PingID in an environment where it is not supported

Details: None

404

NOT_FOUND

None

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

When and details

When: An OATH token or OATH job operation references a token, job, or environment that does not exist

Details: None