Start WebAuthn Authentication

Start WebAuthn authentication process with device trust checking.

Quick Navigation

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

Endpoint

POST /api/v1/webauthn/authenticate/start

Headers

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

Request Body

{
  "email": "user@example.com"
}

Parameters

Field	Type	Required	Description
email	string	Yes	User email address

Response

Success (200)

{
  "success": true,
  "data": {
    "challenge": "base64_encoded_challenge",
    "allowCredentials": [
      {
        "id": "credential_id_base64",
        "type": "public-key",
        "transports": ["usb", "nfc", "ble"]
      }
    ],
    "timeout": 60000,
    "userVerification": "required",
    "rpId": "rivergen.com"
  },
  "message": "WebAuthn authentication challenge generated"
}

Error Codes

Status	Code	Description
400	AUTHENTICATION_START_FAILED	Authentication start failed
404	USER_NOT_FOUND	User not found
404	NO_CREDENTIALS	No WebAuthn credentials found for user

Data Flow

1. User Lookup

   • Find user by email
   • Verify user exists

2. Credentials Query

   • Get user's WebAuthn credentials
   • Filter by user ID

3. Device Trust Check

   • Generate device fingerprint
   • Check if device is trusted
   • Optional: Skip MFA if device is trusted

4. Challenge Generation

   • Generate random challenge (32 bytes)
   • Base64 encode challenge

5. Challenge Storage

   • Store challenge in Redis (5 minutes expiry)
   • Link challenge to user and session

6. WebAuthn Parameters

   • Build authentication options
   • Include allowed credentials
   • Configure user verification

7. Response

   • Return WebAuthn authentication options
   • Include challenge for client

Features

• Generate authentication challenge
• Check device trust status
• Store challenge in Redis
• Return WebAuthn parameters
• Support for passkeys and security keys

Next Steps

1. Client receives challenge
2. User authenticates with device (biometric/pin)
3. Call Complete Authentication with assertion

Example

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

Related Endpoints

• Complete Authentication - Complete WebAuthn authentication