Skip to main content

Pluggable Verification

Step 1: Authentication Initiation​

The UI starts the authentication process by calling:

POST /verification-srv/authentiaction/:method/initiation

Request payload includes:

  • requestid: Unique request identifier
  • identifier: User identifier (email, phone, etc.)
  • verification_challenge: Contains challenge data like challengeid

Response provides:

  • exchange_id: Session management object with expiration
  • sub: Masked subject identifier for the user
  • status_id: Used to track verification status
  • server_challenge: Contains redirect URI for next steps

Step 2 & 3: External Service Integration​

The verification service makes a backend call to an external SPI (Service Provider Interface):

POST /external-srv/verify/

Key process:

  1. Uses client_id from Verification_VerificationSetting to create and cache a token
  2. Calls the configured SPI endpoint with verification data

Request includes:

  • status_id: Links back to the original request
  • identifier: User identifier
  • requestId: Original request ID
  • sub: Subject identifier
  • verification_challenge: Challenge data (flexible structure)

Response (202 Accepted):

  • redirect_uri: Where to redirect the user
  • message: Status message

Step 4 & 5: Status Update​

Updates the verification status once authentication is complete:

PUT /verification-srv/verificationstatus/:status_id

Request:

  • status: Set to "AUTHENTICATED" upon success
  • deviceInformation: Optional device metadata

Architecture Pattern​

This implements an asynchronous polling pattern where:

  1. UI initiates the process
  2. Backend orchestrates with external services
  3. UI polls for status updates using the status_id
  4. External service updates status when verification completes

This design allows for flexible authentication methods (magic links, SMS, email verification, etc.) while maintaining a consistent API interface and reusing existing verification infrastructure.