One-time passwords

One-time passwords (OTPs) provide temporary authentication through single-use codes generated by OrderCloud. This feature enables users to authenticate when they cannot access their regular password but do not want to perform a complete password reset. OTPs serve as a temporary authentication method while maintaining the security of the user's permanent password.

Requesting a one-time password

Prerequisites and setup:

• The marketplace owner must configure the message sender type OneTimePassword
• This configuration enables the OTP delivery system for all users

Request process:

1. Use the POST v1/password/onetimepassword endpoint
2. Provide either Username or Email:
   • Username: Generates OTP for specific user
   • Email: Handles multiple scenarios:
     • Single username: Generates one OTP
     • Multiple usernames: Generates unique OTP for each
     • Email/Username mismatch: No OTP generated

Message content:

• API Client ID for authentication
• Username for identification
• One-time password for temporary access
• All information needed for immediate authentication

Security measures:

• OTPs expire after 10 minutes
• Each OTP is valid for one successful authentication only
• Failed attempts count toward account lockout limits

OneTimePasswordRequest model

Request structure for OTP generation:

{
  "ClientID": "",    // API client identifier
  "Username": "",    // Optional: specific user
  "Email": ""       // Optional: user email
}

Note: Provide either Username or Email, or both if they match.

API endpoints

OTP generation:

• POST v1/password/onetimepassword
  • Generates new OTP
  • Triggers message sender
  • Returns success/failure status

Authentication process

Using an OTP for authentication:

1. Request authentication token:
   • Use password grant type
   • Provide username
   • Use OTP instead of regular password

Example request:

POST https://sandboxapi.ordercloud.io/oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&grant_type=password&username={insert-username}&password={insert-otp}&scope=Shopper

Important considerations:

• Failed authentication attempts with OTPs:
  • Count toward account lockout limits
  • Follow same security rules as regular passwords
• Successful authentication:
  • Invalidates the OTP
  • Prevents reuse of the same code
  • Maintains security of the authentication system

Related reading

• Configuring custom password security
• Using extended properties in custom eCommerce apps
• Configuring user and application data access