Complete WebAuthn Authentication

Complete WebAuthn authentication by verifying assertion and generating tokens. MFA is bypassed.

Quick Navigation

• Endpoint
• Headers
• Request Body
  • Parameters
• Response
  • Success (200)
• Error Codes
• Data Flow
• Features
• Important Notes
• Example
• Related Endpoints

Endpoint

POST /api/v1/webauthn/authenticate/complete

Headers

Header	Required	Description
Content-Type	Yes	application/json
x-device-fingerprint	No	JSON string with device fingerprinting data

Request Body

{
  "credential": {
    "id": "credential_id_base64",
    "rawId": "credential_raw_id_base64",
    "response": {
      "authenticatorData": "authenticator_data",
      "clientDataJSON": "client_data_json",
      "signature": "signature_bytes",
      "userHandle": "user_handle"
    },
    "type": "public-key"
  },
  "email": "user@example.com"
}

Parameters

Field	Type	Required	Description
credential	object	Yes	WebAuthn credential assertion from browser
email	string	Yes	User email address

Response

Success (200)

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "bearer",
    "expires_in": 3600,
    "user_id": 123,
    "email": "user@example.com",
    "display_name": "John Doe",
    "message": "WebAuthn authentication successful"
  },
  "message": "WebAuthn authentication successful"
}

Error Codes

Status	Code	Description
400	AUTHENTICATION_COMPLETION_FAILED	Authentication completion failed
401	INVALID_ASSERTION	Invalid assertion
401	INVALID_CREDENTIAL	Credential not found or invalid
404	CHALLENGE_NOT_FOUND	Authentication challenge not found or expired
404	USER_NOT_FOUND	User not found

Data Flow

1. User Lookup

   • Find user by email
   • Verify user exists

2. Challenge Verification

   • Retrieve challenge from Redis
   • Verify challenge matches
   • Verify challenge not expired

3. Credential Lookup

   • Find credential by ID
   • Verify credential belongs to user

4. Assertion Verification

   • Parse authenticator data
   • Verify signature using public key
   • Verify client data
   • Verify user handle

5. Device Trust Update

   • Generate device fingerprint
   • Update or create trusted device entry

6. Token Generation

   • Generate OAuth2 access token
   • Generate refresh token
   • MFA is bypassed (hardware/biometric auth is strong)

7. Session Creation

   • Create session with IP and user agent
   • Link session to user

8. Credential Update

   • Update credential last_used timestamp
   • Record usage statistics

9. Challenge Cleanup

   • Remove challenge from Redis

10. Audit Logging

    • Log successful authentication
    • Record device and method

Features

• Verify assertion
• Check device trust
• Generate OAuth2 tokens (MFA bypassed for passwordless auth)
• Create session
• MFA is bypassed as hardware/biometric authentication is already strong

Important Notes

• MFA is bypassed for WebAuthn as hardware/biometric authentication provides strong security
• Tokens are generated immediately upon successful authentication
• Device is automatically trusted after successful WebAuthn authentication

Example

curl -X POST https://api.rivergen.com/api/v1/webauthn/authenticate/complete \
  -H "Content-Type: application/json" \
  -H "x-device-fingerprint: {\"screen\":\"1920x1080\"}" \
  -d '{
    "credential": {...},
    "email": "user@example.com"
  }'

Related Endpoints

• Start Authentication - Start authentication process
• List Credentials - View user credentials