Skip to main content

​
Start Login

Initiates the login process by finding a user by handle and generating authentication options.

​
Request Body

​
handle
string
required
User handle (username). 3-32 characters.

​
Response

​
userId
string
User ID (UUID)
​
identity
object
User identity information
​
identity.id
string
Identity ID
​
identity.displayName
string
User’s display name
​
identity.handle
string
User’s handle
​
identity.avatarUrl
string | null
Avatar image URL
​
hasDevices
boolean
Whether user has trusted devices (enables device approval login option)
​
hasPasskeys
boolean
Whether user has passkeys registered (enables passkey login option)
​
authOptions
object | null
WebAuthn authentication options (null if user has no passkeys)
​
authSessionId
string | null
Authentication session ID for passkey login (UUID, null if no passkeys)

​
Error Responses

​
error
string
  • "Account not found" (404) - No user with this handle exists
curl -X POST https://api.ave.com/api/login/start \
  -H "Content-Type: application/json" \
  -d '{
    "handle": "alice_smith"
  }'

​
Login with Passkey

Completes login using WebAuthn passkey authentication.

​
Request Body

​
authSessionId
string
required
Authentication session ID from start login response (UUID format)
​
credential
object
required
WebAuthn authentication response from the authenticator
​
device
object
required
Device information
​
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)

​
Response

​
success
boolean
Always true on successful login
​
sessionToken
string
Session token for authentication (also set as HTTP-only cookie)
​
device
object
Device information (existing device if fingerprint matched, otherwise new)
​
device.id
string
Device ID
​
device.name
string
Device name
​
device.type
string
Device type
​
identities
array
Array of all user identities
​
identities[].id
string
Identity ID
​
identities[].displayName
string
Display name
​
identities[].handle
string
Handle
​
identities[].email
string | null
Email address
​
identities[].avatarUrl
string | null
Avatar URL
​
identities[].bannerUrl
string | null
Banner URL
​
identities[].isPrimary
boolean
Whether this is the primary identity
​
prfEncryptedMasterKey
string | null
PRF-encrypted master key if stored with this passkey (client can decrypt without trust codes)
​
needsMasterKey
boolean
Whether master key recovery is needed (true if no PRF-encrypted key available)

​
Error Responses

​
error
string
  • "Login session expired" (400) - Challenge expired (10 minute timeout)
  • "Passkey not recognized. It may have been registered on a different device or browser." (400) - Passkey not found
  • "Passkey does not belong to this account" (400) - Passkey belongs to different user
  • "Passkey verification failed" (400) - WebAuthn verification failed
curl -X POST https://api.ave.com/api/login/passkey \
  -H "Content-Type: application/json" \
  -d '{
    "authSessionId": "auth_session_uuid",
    "credential": {
      "id": "...",
      "rawId": "...",
      "response": {
        "clientDataJSON": "...",
        "authenticatorData": "...",
        "signature": "..."
      },
      "type": "public-key"
    },
    "device": {
      "name": "MacBook Pro",
      "type": "computer",
      "browser": "Chrome",
      "os": "macOS"
    }
  }'

​
Request Device Approval

Requests login approval from another trusted device. The requesting device generates an ephemeral key pair for secure key exchange.

​
Request Body

​
handle
string
required
User handle (3-32 characters)
​
requesterPublicKey
string
required
Ephemeral public key from the requesting device for E2EE key exchange
​
device
object
required
Device information
​
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)

​
Response

​
requestId
string
Login request ID (UUID) - use this to poll for approval status
​
expiresAt
string
ISO 8601 timestamp when request expires (5 minutes from creation)

​
Error Responses

​
error
string
  • "Account not found" (404) - No user with this handle exists
curl -X POST https://api.ave.com/api/login/request-approval \
  -H "Content-Type: application/json" \
  -d '{
    "handle": "alice_smith",
    "requesterPublicKey": "base64_encoded_public_key",
    "device": {
      "name": "iPad Pro",
      "type": "tablet",
      "browser": "Safari",
      "os": "iPadOS 17"
    }
  }'

​
Check Request Status

Polls the status of a login approval request. When approved, returns session token and encrypted master key.

​
Path Parameters

​
requestId
string
required
Login request ID from request-approval response

​
Response

Pending:
​
status
string
"pending" - Request is waiting for approval
Expired:
​
status
string
"expired" - Request has expired (5 minute timeout)
Denied:
​
status
string
"denied" - Request was denied by user
Approved:
​
status
string
"approved" - Request was approved
​
sessionToken
string
Session token for authentication (also set as HTTP-only cookie)
​
encryptedMasterKey
string
Master key encrypted with requester’s public key (decrypt with requester’s private key)
​
approverPublicKey
string
Approver’s ephemeral public key for key exchange
​
device
object
Created or matched device
​
device.id
string
Device ID
​
device.name
string
Device name
​
device.type
string
Device type
​
identities
array
Array of all user identities (same structure as passkey login)

​
Error Responses

​
error
string
  • "Request not found" (404) - Invalid request ID
  • "Account not found" (404) - User account was deleted
  • "Approval key missing" (400) - Approved but missing public key
curl https://api.ave.com/api/login/request-status/request_uuid

​
Login with Trust Code

Login using a recovery trust code. Trust codes are reusable and decrypt the master key backup.

​
Request Body

​
handle
string
required
User handle (3-32 characters)
​
code
string
required
Trust code (recovery code provided during registration)
​
device
object
required
Device information (same structure as other login methods)

​
Response

​
success
boolean
Always true on successful login
​
sessionToken
string
Session token for authentication
​
encryptedMasterKeyBackup
string | null
Encrypted master key backup (decrypt with the trust code)
​
device
object
Device information (same structure as other login methods)
​
identities
array
Array of all user identities
​
remainingTrustCodes
number
Number of trust codes registered (all are reusable)

​
Error Responses

​
error
string
  • "Account not found" (404) - No user with this handle exists
  • "No trust codes found for your account. You may need to regenerate them from the Security page." (400) - No trust codes configured
  • "Invalid trust code. You have {count} trust code(s) registered." (400) - Trust code doesn’t match
curl -X POST https://api.ave.com/api/login/trust-code \
  -H "Content-Type: application/json" \
  -d '{
    "handle": "alice_smith",
    "code": "XXXX-XXXX-XXXX-XXXX-XXXX-XXXX",
    "device": {
      "name": "New Laptop",
      "type": "computer",
      "browser": "Firefox",
      "os": "Ubuntu"
    }
  }'

​
Recover Master Key

Recovery endpoint to retrieve the encrypted master key backup without creating a new session. Used when a user is already logged in via passkey but doesn’t have the master key locally.

​
Request Body

​
handle
string
required
User handle (3-32 characters)
​
code
string
required
Trust code for verification

​
Response

​
success
boolean
Always true on successful recovery
​
encryptedMasterKeyBackup
string
Encrypted master key backup (decrypt with the trust code)

​
Error Responses

​
error
string
  • "Account not found" (404) - No user with this handle exists
  • "No trust codes found for your account." (400) - No trust codes configured
  • "Invalid trust code." (400) - Trust code doesn’t match
  • "No encryption backup found." (400) - No encrypted backup stored
curl -X POST https://api.ave.com/api/login/recover-key \
  -H "Content-Type: application/json" \
  -d '{
    "handle": "alice_smith",
    "code": "XXXX-XXXX-XXXX-XXXX-XXXX-XXXX"
  }'

​
Logout

Logs out the current session by invalidating the session token.

​
Headers

Accepts authentication via either:
  • Authorization: Bearer {token} header
  • Session cookie (automatically set by login endpoints)

​
Response

​
success
boolean
Always true
curl -X POST https://api.ave.com/api/login/logout \
  -H "Authorization: Bearer {sessionToken}"

​
Authentication Flow

Ave supports three authentication methods:
  1. Call /start with user handle
  2. Use WebAuthn API with authOptions to get credential
  3. Call /passkey with credential and device info
  4. Receive session token and optional PRF-encrypted master key

​
2. Device Approval Login

  1. Call /start to verify user has devices
  2. Call /request-approval with ephemeral public key
  3. User approves on trusted device (via /api/devices/approve-request)
  4. Poll /request-status/:requestId until approved
  5. Receive session token and encrypted master key

​
3. Trust Code Login (Recovery)

  1. Call /trust-code with handle, trust code, and device info
  2. Receive session token and encrypted master key backup
  3. Decrypt backup using the trust code

​
Session Management

  • Duration: Sessions expire after 30 days
  • Storage: Session tokens are set as HTTP-only cookies and also returned in response
  • Authentication: Include token in Authorization: Bearer {token} header or rely on cookie
  • Revocation: Use /logout to invalidate a session

​
Device Fingerprinting

Devices are identified by an optional fingerprint field:
  • If fingerprint matches an existing device, that device is reused and updated
  • If no match, a new device record is created
  • Helps track “New device login” vs “Known device login” for security

​
Activity Logging

All login attempts are logged:
  • Success: Logged with method (passkey/device_approval/trust_code) and device info
  • Failure: Trust code failures logged with severity “warning”
  • Recovery: Key recovery attempts logged separately

Build docs developers (and LLMs) love

Get started for freeTalk to us