Skip to main content

​
Overview

Auth Requests enable passwordless login flows where users can approve authentication requests from other devices. This is commonly used for “Login with Device” functionality.

​
List Auth Requests

Retrieve all authentication requests for the current user. 
GET /auth-requests

​
Response

Returns a list of auth requests with status, device information, and timestamps.
​
id
string
required
Unique identifier for the auth request
​
publicKey
string
Public key for secure communication
​
requestDeviceType
number
Type of device making the request
​
requestIpAddress
string
IP address of the requesting device
​
creationDate
string
When the request was created
​
responseDate
string
When the request was responded to
​
requestApproved
boolean
Whether the request was approved

​
Get Auth Request

Retrieve details of a specific authentication request. 
GET /auth-requests/{id}
​
id
string
required
The auth request ID

​
Get Pending Auth Requests

Retrieve all pending authentication requests awaiting approval. 
GET /auth-requests/pending

​
Response

Returns only auth requests that are pending approval (not yet approved or denied).

​
Create Auth Request

Create a new authentication request for passwordless login. 
curl -X POST "https://api.bitwarden.com/auth-requests" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "publicKey": "...",
    "deviceIdentifier": "abc123",
    "accessCode": "...",
    "type": 0
  }'

​
Request Body

​
email
string
required
Email address of the user
​
publicKey
string
required
Public key for encryption
​
deviceIdentifier
string
required
Unique identifier for the requesting device
​
accessCode
string
required
One-time access code for validation
​
type
number
required
Auth request type (0 = AuthenticateAndUnlock, 1 = Unlock, 2 = AdminApproval)
​
fingerprint
string
Device fingerprint for display
This endpoint does not require authentication when creating user auth requests. Admin approval requests require authentication.

​
Create Admin Auth Request

Create an authentication request requiring admin approval. 
POST /auth-requests/admin-request
​
email
string
required
Email address of the user
​
publicKey
string
required
Public key for encryption
​
type
number
required
Must be 2 (AdminApproval)
This endpoint requires authentication and is used for trusted device encryption workflows.

​
Update Auth Request

Approve or deny an authentication request. 
PUT /auth-requests/{id}
​
id
string
required
The auth request ID

​
Request Body

​
requestApproved
boolean
required
Whether to approve (true) or deny (false) the request
​
key
string
Encrypted key (required when approving)
​
masterPasswordHash
string
Master password hash (required when approving)
​
deviceIdentifier
string
Approving device identifier

​
Example: Approve Request

{
  "requestApproved": true,
  "key": "encrypted_key_data",
  "masterPasswordHash": "hashed_password",
  "deviceIdentifier": "approving_device_id"
}

​
Example: Deny Request

{
  "requestApproved": false
}

​
Get Auth Request Response

Retrieve the response for an auth request (used by requesting device). 
GET /auth-requests/{id}/response?code={accessCode}
​
id
string
required
The auth request ID
​
code
string
required
Access code provided when creating the request
This endpoint does not require authentication. The access code serves as verification.

​
Auth Request Workflow

​
Login with Device Flow

  1. Requesting Device: Creates auth request with POST /auth-requests
  2. Requesting Device: Polls GET /auth-requests/{id}/response for approval
  3. Approving Device: Views pending requests with GET /auth-requests/pending
  4. Approving Device: Approves request with PUT /auth-requests/{id}
  5. Requesting Device: Receives encrypted key and completes authentication

​
Admin Approval Flow

  1. User Device: Creates admin auth request with POST /auth-requests/admin-request
  2. Admin: Views request in organization admin console
  3. Admin: Approves or denies request
  4. User Device: Receives response and completes setup
Auth requests have a limited lifetime and expire if not approved. Only approve requests from devices you recognize.

Build docs developers (and LLMs) love

Get started for freeTalk to us