Start WebAuthn Registration

Start WebAuthn registration process by generating a registration challenge.

Quick Navigation

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

Endpoint

POST /api/v1/webauthn/register/start

Headers

Header	Required	Description
Authorization	Yes	Bearer <access_token>
Content-Type	Yes	application/json

Request Body

{
  "device_name": "iPhone 14 Pro"
}

Parameters

Field	Type	Required	Description
device_name	string	Yes	Name for the WebAuthn credential

Response

Success (201)

{
  "success": true,
  "data": {
    "challenge": "base64_encoded_challenge",
    "rp": {
      "name": "RiverGen",
      "id": "rivergen.com"
    },
    "user": {
      "id": "base64_user_id",
      "name": "user@example.com",
      "displayName": "John Doe"
    },
    "pubKeyCredParams": [
      {
        "type": "public-key",
        "alg": -7
      }
    ],
    "authenticatorSelection": {
      "userVerification": "required",
      "residentKey": "preferred"
    },
    "timeout": 60000,
    "attestation": "none"
  },
  "message": "WebAuthn registration challenge generated"
}

Error Codes

Status	Code	Description
400	REGISTRATION_START_FAILED	Registration start failed
401	UNAUTHORIZED	Invalid or missing token
404	USER_NOT_FOUND	User not found

Data Flow

1. Authentication

   • Verify access token
   • Get current user

2. Challenge Generation

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

3. Challenge Storage

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

4. WebAuthn Parameters

   • Build relying party information
   • Build user information
   • Configure credential parameters
   • Set authenticator selection

5. Response

   • Return WebAuthn registration options
   • Include challenge for client

Features

• Generate registration challenge
• Store challenge in Redis
• Return WebAuthn parameters
• Support for passkeys and security keys
• User verification required

Next Steps

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

Example

curl -X POST https://api.rivergen.com/api/v1/webauthn/register/start \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "device_name": "iPhone 14 Pro"
  }'

Related Endpoints

• Complete Registration - Complete WebAuthn registration