Bitwarden Public API

The Bitwarden Public API provides organizations a suite of tools for managing members, collections, groups, event logs, and policies.

The Public API is a RESTful API with predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

The Public API is compatible with the OpenAPI Specification (OAS3) and publishes a compliant swagger.json definition file. Explore the OpenAPI Specification using the Swagger UI:

• For public cloud-hosted instances: https://bitwarden.com/help/api/

• For self-hosted instances: https://your.domain.com/api/docs/

For cloud-hosted, https://api.bitwarden.com or https://api.bitwarden.eu.

For self-hosted, https://your.domain.com/api.

For cloud-hosted, https://identity.bitwarden.com/connect/token or https://identity.bitwarden.eu/connect/token.

For self-hosted, https://your.domain.com/identity/connect/token.

The API uses bearer access tokens to authenticate with protected API endpoints. Bitwarden uses an OAuth2 Client Credentials application request flow to grant bearer access tokens from the endpoint. Authentication requests take client_id and client_secret as required parameters.

The API Key client_id and client_secret can be obtained by an owner from the Admin Console vault by navigating to Settings → Organization info screen and scrolling down to the API key section:

If, as an owner, you want to share the API key with an admin or other user, use a secure communication method like Bitwarden Send.

To obtain a bearer access token, make a POST request with Content-Type: application/x-www-form-urlencoded with your client_id and client_secret to the authentication endpoint. When using the API for organization management, you will always use grant_type=client_credentials and scope=api.organization. For example:

BashCopy
curl -X POST \
  https://identity.bitwarden.com/connect/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&scope=api.organization&client_id=<ID>&client_secret=<SECRET>'

This request will result in the following response:

BashCopy
{
  "access_token": "<TOKEN>",
  "expires_in": 3600,
  "token_type": "Bearer"
}

In this response, 3600 represents the expiration value (in seconds), meaning this token is valid for 60 minutes after being issued. Making an API call with an expired token will return a 401 Unauthorized response code.

The Bitwarden Public API communicates with application/json requests and responses, with one exception:

The authentication endpoint expects an application/x-www-form-urlencoded request, however will respond with application/json.

BashCopy
curl -X GET \
  https://api.bitwarden.com/public/collections \
  -H 'Authorization: Bearer <TOKEN>'

Where <TOKEN> is the value for the access_token: key in the obtained bearer access token.

This request will result in a response:

BashCopy
{
  "object": "list",
  "data": [
    {
      "object": "event",
      "type": 1000,
      "itemId": "string",
      "collectionId": "string",
      "groupId": "string",
      "policyId": "string",
      "memberId": "string",
      "actingUserId": "string",
      "date": "2020-11-04T15:01:21.698Z",
      "device": 0,
      "ipAddress": "xxx.xx.xxx.x"
    }
  ],
  "continuationToken": "string"
}

Bitwarden has a public status page, where you can find information about service health and incidents for all services including the Public API.

The Bitwarden Public API uses conventional HTTP response codes to indicate the success or failure of an API request:

For more information about using the Bitwarden Public API, see the following articles:

• Bitwarden Public API OAS Specification

• Event logs