Skip to main content

​
Authentication

All security endpoints require authentication via the requireAuth middleware. Include a valid session token in your request.

​
Get Security Overview

Retrieve an overview of the user’s security settings, including all passkeys and trust code information.

​
Response

​
passkeys
array
Array of passkey objects
​
id
string
Unique identifier for the passkey (base64url encoded credential ID)
​
name
string
User-assigned name for the passkey
​
createdAt
string
Timestamp of when the passkey was created
​
lastUsedAt
string | null
Timestamp of when the passkey was last used for authentication
​
deviceType
string
Type of device (e.g., “singleDevice” or “multiDevice”)
​
trustCodesRemaining
number
Number of unused trust codes available
​
securityQuestionIds
array
Empty array (security questions have been removed from Ave)

​
Passkey Registration

​
Start Passkey Registration

Generate WebAuthn registration options to begin passkey registration. Returns options that should be passed to the WebAuthn API.

​
Response

​
options
object
WebAuthn registration options object
​
challenge
string
Base64url-encoded challenge (valid for 5 minutes)
​
rp
object
Relying party information
​
user
object
User information for the credential
​
pubKeyCredParams
array
Supported public key credential parameters
​
authenticatorSelection
object
Authenticator selection criteria (requires resident key and user verification)
​
excludeCredentials
array
Array of existing passkey IDs to exclude from registration

​
Complete Passkey Registration

Complete passkey registration by verifying the WebAuthn credential response.

​
Request Body

​
credential
object
required
WebAuthn credential response from navigator.credentials.create()
​
name
string
Optional name for the passkey (max 64 characters). Defaults to “New Passkey” if not provided.
​
prfEncryptedMasterKey
string
Optional PRF-encrypted master key if the passkey supports PRF extension

​
Response

​
passkey
object
The created passkey object
​
id
string
Unique identifier for the passkey
​
name
string
User-assigned name
​
createdAt
string
Creation timestamp
​
deviceType
string
Device type

​
Error Responses

  • 400 - Registration session expired (challenge expired after 5 minutes)
  • 400 - Invalid origin (must be localhost or configured production origin)
  • 400 - Invalid credential format
  • 400 - Passkey verification failed

​
Activity Log

Successful passkey registration logs a passkey_added action with severity info.

​
Update Passkey

Update a passkey’s name or PRF-encrypted master key.

​
Path Parameters

​
passkeyId
string
required
The unique identifier of the passkey to update

​
Request Body

​
name
string
New name for the passkey (1-64 characters)
​
prfEncryptedMasterKey
string
New PRF-encrypted master key

​
Response

​
success
boolean
Returns true if the update was successful

​
Error Responses

  • 404 - Passkey not found or does not belong to the authenticated user

​
Master Key Unlock

​
Start Master Key Unlock

Initiate master key unlock process using a PRF-enabled passkey. Only passkeys with a stored PRF-encrypted master key can be used.

​
Response

​
unlockSessionId
string
Unique session ID for this unlock attempt (valid for 5 minutes)
​
options
object
WebAuthn authentication options
​
challenge
string
Base64url-encoded challenge
​
allowCredentials
array
Array of passkey IDs that have PRF-encrypted master keys

​
Error Responses

  • 400 - No PRF-enabled passkeys found (error code: “no_prf_passkey”)

​
Finish Master Key Unlock

Complete master key unlock by verifying the WebAuthn authentication response.

​
Request Body

​
unlockSessionId
string
required
The unlock session ID from the start endpoint
​
credential
object
required
WebAuthn credential response from navigator.credentials.get()

​
Response

​
prfEncryptedMasterKey
string
The PRF-encrypted master key that can be decrypted using the PRF output

​
Error Responses

  • 400 - Unlock session expired (error code: “unlock_session_expired”)
  • 403 - Session does not belong to authenticated user (error code: “forbidden”)
  • 400 - Invalid origin (error code: “invalid_origin”)
  • 400 - Invalid credential format (error code: “invalid_credential_format”)
  • 404 - Passkey not found (error code: “passkey_not_found”)
  • 400 - Passkey verification failed (error code: “passkey_verification_failed”)
  • 400 - No PRF master key stored on this passkey (error code: “no_prf_master_key”)

​
Delete Passkey

Delete a passkey. Cannot delete the user’s only passkey.

​
Path Parameters

​
passkeyId
string
required
The unique identifier of the passkey to delete

​
Response

​
success
boolean
Returns true if the deletion was successful

​
Error Responses

  • 404 - Passkey not found or does not belong to the authenticated user
  • 400 - Cannot delete your only passkey

​
Activity Log

Deleting a passkey logs a passkey_removed action with severity warning.

​
Trust Codes

​
Regenerate Trust Codes

Regenerate trust codes for account recovery. Deletes all existing trust codes and creates 2 new ones.
This action invalidates all previously generated trust codes. Store the new codes securely.

​
Response

​
codes
array
Array of 2 newly generated trust codes (plain text). These codes will never be shown again.

​
Activity Log

Regenerating trust codes logs a trust_codes_regenerated action with severity warning.

​
Security Questions (Deprecated)

​
Update Security Questions

This endpoint is deprecated and will return a 410 Gone error. Security questions have been removed from Ave.

​
Request Body

​
questions
array
required
Array of 3 question/answer objects

​
Response

  • 410 - Security questions have been removed (error: “security_questions_removed”)

Build docs developers (and LLMs) love

Get started for freeTalk to us