Skip to main content

​
Start Registration

Initiates the registration process by checking handle availability and generating WebAuthn registration options.

​
Request Body

​
handle
string
required
User handle (username). Must be 3-32 characters, containing only letters, numbers, and underscores.
  • Min length: 3
  • Max length: 32
  • Pattern: ^[a-zA-Z0-9_]+$

​
Response

​
options
object
WebAuthn registration options generated by @simplewebauthn/server
​
tempUserId
string
Temporary user ID for this registration session (UUID format)

​
Error Responses

​
error
string
Error message when registration cannot proceed
  • "Handle is already taken" (400) - Handle already exists in the system
curl -X POST https://api.ave.com/api/register/start \
  -H "Content-Type: application/json" \
  -d '{
    "handle": "alice_smith"
  }'

​
Complete Registration

Completes the registration process by verifying the WebAuthn credential and creating the user account.

​
Request Body

​
tempUserId
string
required
Temporary user ID from the start registration response (UUID format)
​
credential
object
required
WebAuthn registration response from the authenticator
​
identity
object
required
User identity information
​
identity.displayName
string
required
Display name for the user (1-64 characters)
​
identity.handle
string
required
User handle (3-32 characters)
​
identity.email
string
Email address (optional, must be valid email format)
​
identity.birthday
string
Birthday in string format (optional)
​
identity.avatarUrl
string
URL to user’s avatar image (optional, must be valid URL)
​
identity.bannerUrl
string
URL to user’s banner image (optional, must be valid URL)
​
device
object
required
Device information for the registration
​
device.name
string
required
Device name (max 64 characters)
​
device.type
enum
required
Device type: "phone", "computer", or "tablet"
​
device.browser
string
Browser name (optional)
​
device.os
string
Operating system (optional)
​
device.fingerprint
string
Unique device fingerprint (optional, max 64 characters)
​
prfEncryptedMasterKey
string
PRF-encrypted master key if the passkey supports the PRF extension (optional)

​
Response

​
success
boolean
Always true on successful registration
​
sessionToken
string
Session token for authentication (also set as HTTP-only cookie)
​
trustCodes
string[]
Array of 2 trust codes for account recovery. User must save these securely.
​
user
object
Created user information
​
user.id
string
User ID (UUID)
​
identity
object
Created identity information
​
identity.id
string
Identity ID (UUID)
​
identity.displayName
string
User’s display name
​
identity.handle
string
User’s handle (lowercase)
​
identity.email
string | null
User’s email address
​
identity.avatarUrl
string | null
Avatar image URL
​
identity.bannerUrl
string | null
Banner image URL
​
identity.isPrimary
boolean
Whether this is the primary identity (always true for first identity)
​
device
object
Created device information
​
device.id
string
Device ID (UUID)
​
device.name
string
Device name
​
device.type
string
Device type

​
Error Responses

​
error
string
Error message when registration fails
  • "Registration session expired" (400) - The challenge has expired (15 minute timeout)
  • "Passkey verification failed" (400) - WebAuthn verification failed
curl -X POST https://api.ave.com/api/register/complete \
  -H "Content-Type: application/json" \
  -d '{
    "tempUserId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "credential": {
      "id": "...",
      "rawId": "...",
      "response": {
        "clientDataJSON": "...",
        "attestationObject": "...",
        "transports": ["internal"]
      },
      "type": "public-key"
    },
    "identity": {
      "displayName": "Alice Smith",
      "handle": "alice_smith",
      "email": "[email protected]"
    },
    "device": {
      "name": "iPhone 15",
      "type": "phone",
      "browser": "Safari",
      "os": "iOS 17"
    }
  }'

​
Check Handle Availability

Checks if a handle is available for registration.

​
Path Parameters

​
handle
string
required
Handle to check (converted to lowercase automatically)

​
Response

​
available
boolean
Whether the handle is available for registration
​
reason
string
Reason why handle is unavailable (only present when available is false)
  • "Handle must be 3-32 characters" - Invalid length
  • "Handle can only contain letters, numbers, and underscores" - Invalid characters
curl https://api.ave.com/api/register/check-handle/alice_smith

​
Finalize Master Key Backup

Finalizes the master key backup after the client encrypts it with the real trust codes. Requires authentication.

​
Request Body

​
encryptedMasterKeyBackup
string
required
Encrypted master key backup (encrypted with trust codes)

​
Headers

​
Authorization
string
required
Bearer token: Bearer {sessionToken}

​
Response

​
success
boolean
Always true on successful update
curl -X POST https://api.ave.com/api/register/finalize-backup \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {sessionToken}" \
  -d '{
    "encryptedMasterKeyBackup": "..."
  }'

​
Validation Rules

​
Handle Validation

  • Length: 3-32 characters
  • Pattern: Only letters (a-z, A-Z), numbers (0-9), and underscores (_)
  • Case: Automatically converted to lowercase
  • Uniqueness: Must not already exist in the system

​
Identity Fields

  • displayName: 1-64 characters, required
  • email: Must be valid email format (optional)
  • avatarUrl/bannerUrl: Must be valid URL format (optional)

​
Device Fields

  • name: Maximum 64 characters
  • type: Must be one of: phone, computer, tablet
  • fingerprint: Maximum 64 characters (optional)

​
Session Duration

  • Sessions expire after 30 days
  • Challenge expires after 15 minutes

​
Trust Codes

  • Count: 2 codes generated per registration
  • Format: Hyphen-separated format (e.g., XXXX-XXXX-XXXX-XXXX-XXXX-XXXX)
  • Security: Hashed before storage using SHA-256
  • Usage: Reusable for account recovery

Build docs developers (and LLMs) love

Get started for freeTalk to us