Recovery codes service API references

The OneWelcome Identity Platform provides the recovery codes service for secure backup authentication. The recovery codes service enables users to recover access to their accounts through single-use recovery codes when primary authentication methods are unavailable. It includes features for code generation, validation with brute force protection, regeneration, import capabilities, and tenant-specific configuration management.

Recovery codes service APIs

The recovery codes service includes the following APIs:

• Recovery codes API: Provides endpoints for the following tasks:

  • Generate recovery codes: Create a new set of recovery codes for an identity (fails if codes already exist).

  • Regenerate recovery codes: Delete existing codes and generate a new set (always succeeds).

  • Validate recovery code: Validate and consume a single recovery code with brute force protection and automatic unlocking.

  • Import recovery codes: Import plaintext recovery codes for migration from other systems.

  • Get recovery code count: Retrieve the number of remaining unused recovery codes for an identity.

  • Delete all recovery codes: Remove all recovery codes and brute force protection records for an identity.

• Configuration API: Provides endpoints for the following tasks:

  • Get recovery code configuration: Retrieve tenant-level configuration including code count, length, max validation attempts, and auto-unlock timeout.

  • Update recovery code configuration: Partially update one or more configuration fields for the tenant (PATCH semantics).

Authentication

All Recovery Codes Service API endpoints require OAuth2 Bearer tokens with the appropriate permissions.