Auth Requests API

Passwordless authentication using device approval flows

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

curl -X POST "https://api.bitwarden.com/auth-requests" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "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.