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.