TOTP service API references

The OneWelcome Identity Platform provides the time-based one-time password (TOTP) service for TOTP authentication. The TOTP service enables secure multi-factor authentication through device enrollment, code validation, device management, and migration capabilities. It supports standard TOTP algorithms (HmacSHA1, HmacSHA256, HmacSHA512) with configurable code length and time periods.

TOTP service APIs

The TOTP service includes the following APIs:

• Enrollment API: Provides endpoints for the following tasks:

  • Initiate TOTP enrollment: Generate a shared secret and OTP URI for QR code scanning with a cached enrollment transaction.

  • Validate and complete enrollment: Validate the first TOTP code to complete the enrollment process and persist the device.

• Validation API: Provides endpoints for the following task:

  • Validate TOTP code: Validate a TOTP code against all enrolled devices for an identity, returning the matching device ID on success.

• Device Management API: Provides endpoints for the following tasks:

  • List all TOTP devices: Retrieve all enrolled TOTP devices for an identity with decrypted device names.

  • Get specific TOTP device: Retrieve details of a specific TOTP device for debugging purposes.

  • Update TOTP device: Update device properties such as the device name.

  • Delete TOTP device: Remove a specific TOTP device from an identity.

  • Manage TOTP configuration: Get and update the tenant-level TOTP configuration including algorithm, code digits, time period, and clock skew settings.

• Import API: Provides endpoints for the following task:

  • Import TOTP device data: Import existing TOTP device enrollment data directly into the database, supporting migration from other systems.

Authentication

All TOTP Service API endpoints require OAuth2 Bearer tokens with the appropriate audience.