Bitwarden Public API
The Bitwarden Public API provides organizations a suite of tools for managing members, collections, groups, event logs, and policies.
This API does not allow for management of individual vault items. If this is what you need to accomplish, use the Vault Management API instead.
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:
For self-hosted instances:
Access to the Bitwarden Public API is available customers on all Enterprise and Teams organizations. For more information, see About Bitwarden Plans.
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_secret as required parameters.
The API key used to authenticate with the Public API is not the same as the personal API Key. Organization API keys will have a
client_id with format
"organization.ClientId", whereas personal API keys will have a
client_id with format
The API Key
client_secret can be obtained by an owner from the web vault by navigating to organization Settings → My Organization 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.
Your organization API key enables full access to your organization. Keep your API key private. If you believe your API key has been compromised, select Settings > Organization info > Rotate API key button on this screen. Active implementations of your current API key will need to be reconfigured with the new key before use.
To obtain a bearer access token, make a
POST request with
Content-Type: application/x-www-form-urlencoded with your
client_secret to the authentication endpoint. When using the API for organization management, you will always use
scope=api.organization. For example:
This request will result in the following response:
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
<TOKEN> is the value for the
access_token: key in the obtained bearer access token.
This request will result in a response:
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: