Public API
The Bitwarden Public API provides organizations a suite of tools for managing members, collections, groups, event logs, and policies. More information about the Public API is available in the Help Center.
Differences with the private API
Most developers will be more familiar with the private API used by our client applications. The Public API is different in several key areas:
| Private API | Public API |
|---|---|
| Located at https://api.bitwarden.com | Located at https://api.bitwarden.com/public |
| Used by official Bitwarden client applications | Used by third parties, usually in custom integrations |
| Broad scope -- can be used for anything | Narrow scope -- can only be used to manage organizations |
| Can be changed without notice (but subject to the official support cycle) | Must give notice (such as deprecation warnings) for certain changes |
| Utilizes user credentials for authentication | Utilizes organization API key for authentication |
Development guidelines
- Avoid making breaking changes -- these are any changes that would require existing users of the API to update their integrations to avoid errors or unexpected behavior -- for example, make new properties optional, so that existing integrations do not have to supply a value
- If you must make breaking changes, consider how to give advance warning to existing users. Communicate with Engineering, Product, and Customer Success Integration teams to coordinate any notice required and minimize impact
- Do not use the same request/response models as the private API
- Use xmldoc comments to add documentation to your endpoints and models. These will be included in the SwaggerUI output
Developing locally
When running in dev mode the Bitwarden server includes a SwaggerUI instance, similar to the one found on our Help Center.
SwaggerUI can help you test any changes you make to the Public API without having to write your own HTTP requests. You can also check how your xmldoc comments will be presented by SwaggerUI when the Help Center is updated.
To use SwaggerUI:
- Start your local development server (Api and Identity projects) and Web Vault
- Navigate to http://localhost:4000/docs
- Click "Authorize"
- In a separate tab, open the Web Vault and navigate to your Organization Settings page. Click "View API Key"
- Enter your organization's client_id and client_secret from the Web Vault into Swagger. You can now close the Web Vault and continue in Swagger
- In the Scopes section, click "select all"
- Click "Authorize" to close the dialog
- You should receive a confirmation dialog. Click "Close"
You can now test the Public API by expanding any section, clicking "Try it out", editing the request, and clicking Execute. The response will be displayed below. You can also verify that your request worked by manually inspecting the organization in the Web Vault.