Action-challenge API references

The OneWelcome Identity Platform provides the Action-Challenge Service (ACS). The Action-Challenge Service generates one-time tokens and codes that challenge a user before allowing or approving a certain action. After the user completes a challenge, it is up to the consuming service to finalize the action (for example, password reset, app-to-web SSO, or email attribute verification).

The service supports multiple challenge types (EMAIL_OTP, SMS_OTP, EMAIL_LINK, and TOKEN), multi-tenancy with complete data isolation, and configurable policies that govern challenge behavior.

Action-challenge APIs

The Action-Challenge Service includes the following APIs:

• Core API: Provides endpoints for managing the full lifecycle of challenges:

  • Create challenge: Initiate a new challenge for a user action using a named policy alias.

  • Get challenge status: Retrieve the current state and metadata of an existing challenge.

  • Cancel challenge: Explicitly cancel an active challenge in the ISSUED or VERIFIED state.

  • Answer challenge: Submit an OTP code or token value to verify a challenge.

  • Resend challenge: Re-deliver the OTP or magic link to the original recipient.

  • Complete challenge: Finalize a verified challenge to confirm that the associated user action was approved.

• Management API: Provides endpoints for administering challenge policies:

  • Create challenge policy: Define a named policy governing challenge behavior, including type, conditions, and delivery template.

  • Get challenge policy: Retrieve a specific policy by its ID.

  • List challenge policies: Retrieve a paginated list of all policy IDs.

  • Update challenge policy: Fully replace an existing policy using optimistic locking.

  • Delete challenge policy: Remove a challenge policy.

• Global Configuration API: Provides endpoints for managing runtime service settings:

  • Get global configuration: Retrieve all current runtime configuration properties.

  • Update global configuration: Replace all global configuration properties. Changes take effect immediately.

Authentication

All action-challenge API endpoints require OAuth2 or JWT bearer tokens. The tenant context is derived from the JWT token claims.

Both OAuth2 (M2M client credentials) and JWT bearer (S2S) tokens are accepted for all endpoints.

Core API scopes

Management API scopes

Global configuration API scopes