PingDirectory API Reference

Deliver One Time Password

The deliver one-time password extended operation is used to indicate that the server should generate a one-time password for a user, store it in the user’s entry, and deliver it to the user through a method like email or SMS. This operation is heavily based on the DeliverOneTimePasswordExtendedRequest class in the LDAP SDK.

The request body is a JSON object with the following fields:

  • dn

    An optional string field whose value is the full DN of the user that is attempting to authenticate. Exactly one of the dn and username fields must be present.

  • username

    An optional string field whose value is the username for the user that is attempting to authenticate. Exactly one of the dn and username fields must be present.

  • staticPassword

    A mandatory string field whose value is the static password for the target user.

  • preferredDeliveryMechanisms

    An optional string array field whose values are the names of the OTP delivery mechanisms that the client wants to use, in order from most preferred to least preferred. The names that are available for use depends on the server’s configuration. If this is not provided, then the server will automatically choose a delivery mechanism for the user.

The response body is created from the deliver one-time password extended result. The response is a JSON object with the following fields:

  • resultCode

    A mandatory JSON object that contains the following fields:

    • value — The integer value for the LDAP result code. This is required.

    • name — A name for the LDAP result code. This is optional but recommended.

  • diagnosticMessage

    An optional string field that holds a human-readable message with additional information about the operation.

  • deliveryMechanism

    An optional string field that holds the name of the delivery mechanism that was used to send the one-time password to the user. This will be present if the one-time password was successfully sent.

  • recipientDN

    An optional string field that holds the DN of the user for whom the password was generated and delivered. This will be present if the one-time password was successfully sent.

  • recipientID

    An optional string field that holds the delivery mechanism-specific identifier to which the one-time password was sent, like an email address if the password was delivered via email or a mobile phone number of the password was delivered by SMS. This will be present if the one-time password was successfully sent, and if the delivery mechanism used to send it provided a recipient ID.

  • deliveryMessage

    An optional string field that holds a message that may provide additional information about the one-time password delivery attempt.