Skip to main content
All device endpoints require authentication. Include the session token in the Authorization header as Bearer {token} or rely on the session cookie.

​
List Devices

Returns all devices associated with the authenticated user, ordered by most recently seen.

​
Headers

​
Authorization
string
required
Bearer token: Bearer {sessionToken}

​
Response

​
devices
array
Array of device objects
​
devices[].id
string
Device ID (UUID)
​
devices[].name
string
Device name
​
devices[].type
string
Device type: "phone", "computer", or "tablet"
​
devices[].browser
string | null
Browser name
​
devices[].os
string | null
Operating system
​
devices[].lastSeenAt
string
ISO 8601 timestamp of last activity
​
devices[].isActive
boolean
Whether device is currently active (not revoked)
​
devices[].isCurrent
boolean
Whether this is the current session’s device
curl https://api.ave.com/api/devices \
  -H "Authorization: Bearer {sessionToken}"

​
Get Pending Login Requests

Returns pending login approval requests for the authenticated user’s account.

​
Headers

​
Authorization
string
required
Bearer token: Bearer {sessionToken}

​
Response

​
requests
array
Array of pending login request objects
​
requests[].id
string
Request ID (UUID)
​
requests[].deviceName
string | null
Requesting device name
​
requests[].deviceType
string | null
Requesting device type
​
requests[].browser
string | null
Requesting device browser
​
requests[].os
string | null
Requesting device OS
​
requests[].ipAddress
string | null
IP address of the login request
​
requests[].createdAt
string
ISO 8601 timestamp when request was created
​
requests[].expiresAt
string
ISO 8601 timestamp when request expires (5 minutes from creation)
​
requests[].requesterPublicKey
string
Ephemeral public key from requesting device for E2EE key exchange
curl https://api.ave.com/api/devices/pending-requests \
  -H "Authorization: Bearer {sessionToken}"

​
Approve Login Request

Approves a pending login request by encrypting and sending the master key to the requesting device.

​
Headers

​
Authorization
string
required
Bearer token: Bearer {sessionToken}

​
Request Body

​
requestId
string
required
Login request ID (UUID)
​
encryptedMasterKey
string
required
Master key encrypted with the requester’s public key (from requesterPublicKey)
​
approverPublicKey
string
required
Approver’s ephemeral public key for key exchange

​
Response

​
success
boolean
Always true on successful approval

​
Error Responses

​
error
string
  • "Request not found" (404) - Invalid request ID
  • "Request already handled" (400) - Request was already approved or denied
  • "Request expired" (400) - Request has expired (5 minute timeout)
  • "Unauthorized" (403) - Request doesn’t belong to the authenticated user
curl -X POST https://api.ave.com/api/devices/approve-request \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {sessionToken}" \
  -d '{
    "requestId": "request_uuid",
    "encryptedMasterKey": "encrypted_master_key_base64",
    "approverPublicKey": "approver_public_key_base64"
  }'

​
Deny Login Request

Denies a pending login request.

​
Headers

​
Authorization
string
required
Bearer token: Bearer {sessionToken}

​
Request Body

​
requestId
string
required
Login request ID (UUID)

​
Response

​
success
boolean
Always true on successful denial

​
Error Responses

​
error
string
  • "Request not found" (404) - Invalid request ID
  • "Unauthorized" (403) - Request doesn’t belong to the authenticated user
curl -X POST https://api.ave.com/api/devices/deny-request \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {sessionToken}" \
  -d '{
    "requestId": "request_uuid"
  }'

​
Update Device Name

Updates the name of a device.

​
Headers

​
Authorization
string
required
Bearer token: Bearer {sessionToken}

​
Path Parameters

​
deviceId
string
required
Device ID (UUID)

​
Request Body

​
name
string
required
New device name (1-64 characters)

​
Response

​
success
boolean
Always true on successful update

​
Error Responses

​
error
string
  • "Device not found" (404) - Device doesn’t exist or doesn’t belong to user
curl -X PATCH https://api.ave.com/api/devices/device_uuid \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {sessionToken}" \
  -d '{
    "name": "My New iPhone"
  }'

​
Revoke Device

Revokes a device, removing it from trusted devices and invalidating all its sessions. Cannot revoke the current session’s device.

​
Headers

​
Authorization
string
required
Bearer token: Bearer {sessionToken}

​
Path Parameters

​
deviceId
string
required
Device ID (UUID)

​
Response

​
success
boolean
Always true on successful revocation

​
Error Responses

​
error
string
  • "Cannot revoke current device" (400) - Attempted to revoke the device of the current session
  • "Device not found" (404) - Device doesn’t exist or doesn’t belong to user
curl -X DELETE https://api.ave.com/api/devices/device_uuid \
  -H "Authorization: Bearer {sessionToken}"

​
Device Lifecycle

​
Device Creation

Devices are created automatically during:
  • Registration (/api/register/complete)
  • Login with passkey (/api/login/passkey)
  • Login with trust code (/api/login/trust-code)
  • Approved device login (/api/login/request-status/:requestId when approved)

​
Device Fingerprinting

The optional fingerprint field (max 64 characters) uniquely identifies a device:
  • When logging in, if the fingerprint matches an existing device, that device is reused
  • The device’s lastSeenAt, name, browser, and os are updated
  • If no match is found, a new device record is created
This helps distinguish between “New device login” and “Known device login” for security purposes.

​
Device Cleanup

Devices are automatically marked as inactive:
  • When manually revoked via DELETE /api/devices/:deviceId
  • When inactive for 14+ days (automatic cleanup process)
Inactive devices:
  • Have all their sessions deleted
  • Are marked with isActive: false
  • Are kept in the database for audit purposes

​
Login Approval Flow

  1. Request: New device calls /api/login/request-approval with ephemeral public key
  2. Notification: Trusted devices receive WebSocket notification and/or push notification
  3. Fetch: Trusted device calls /api/devices/pending-requests to get details
  4. Decision: User reviews request details (device name, type, IP, etc.)
  5. Encrypt: Trusted device encrypts master key with requester’s public key
  6. Approve/Deny: Call /api/devices/approve-request or /api/devices/deny-request
  7. Complete: Requesting device polls /api/login/request-status/:requestId and receives encrypted key

​
Security Features

  • E2EE Key Exchange: Uses ephemeral key pairs to securely transfer master key
  • 5 Minute Timeout: Requests expire automatically
  • WebSocket + Push: Real-time notifications to trusted devices
  • IP Tracking: Shows requesting device’s IP address for verification
  • Activity Logging: All approvals/denials logged with severity levels

​
Activity Logging

Device operations are logged:
  • device_removed (severity: warning) - Manual device revocation
  • device_auto_removed (severity: info) - Automatic cleanup after 14 days
  • login_approved (severity: info) - Approval of login request
  • login_denied (severity: warning) - Denial of login request

Build docs developers (and LLMs) love

Get started for freeTalk to us