Bitwarden 公共 API

Bitwarden Public API 为组织提供了一套用于管理成员、集合、群组、事件日志和策略的工具。

对于密码库项目管理，请使用 CLI。对密码库项目的访问依赖于密码库解密，解密必须使用主密码。

此 Public API 是一种 RESTful API，RESTful API 具有可预测的面向资源的 URL，接受 JSON 编码的请求正文，返回 JSON 编码的响应，并使用标准的 HTTP 响应代码、验证和动态词。

此 Public API 与 OpenAPI 规范 (OAS3) 兼容，并发布兼容的 swagger.json 定义文件。使用 Swagger UI 探索 OpenAPI 规范：

对于公共云托管实例：https://bitwarden.com/help/api/
对于自托管实例：https://your.domain.com/api/docs/

以下计划的客户可以访问 Bitwarden 公共 API：经典 2019 企业组织、当前的企业组织和当前的团队组织。有关更多信息，请参阅关于 Bitwarden 计划。

[译者注]：Swagger-UI 是一套 HTML/CSS/JS 框架，用于解析遵守 Swagger 规范的 JSON 或 YAML 文件，展示 swagger-editor 生成的 API 文档，还可以在其中调试 API。它将我们编写的 OpenAPI 规范呈现为交互式的 API 文档，使用浏览器来查看并且操作我们的 RESTful API。
Swagger 官方网站、Swagger 介绍 1、Swagger 介绍 2、Swagger UI 介绍。

端点

基本 URL

对于云托管：https://api.bitwarden.com

对于自托管：https://your.domain.com/api

验证端点

对于云托管：https://identity.bitwarden.com/connect/token

对于自托管：https://your.domain.com/identity/connect/token

验证

API 使用承载访问令牌对受保护的 API 端点进行验证。Bitwarden 使用 OAuth2 客户端凭据应用程序请求流来从端点授予承载访问令牌。验证请求将 client_id 和 client_secret 作为必要的参数。

用于验证公共 API 的 API 密钥与个人 API 密钥是不同的。组织 API 密钥的 client_id 格式为 "organization.ClientId"，而个人 API 密钥的 client_id 格式为 "user.clientId"。

API 密钥 client_id 和 client_secret 可以由所有者从网页密码库获得，方法是通过导航到组织设置 → 我的组织，并向下滚动到 API 密钥部分：

作为所有者，如果您想与管理员或其他用户分享 API 密钥，请使用安全的通信方式，比如 Bitwarden Send。

您的组织 API 密钥具有对您的组织的完全访问权限。请妥善保管您的 API 密钥。如果您认为您的 API 密钥已经泄露，请在此界面上选择轮换 API 密钥按钮。当前 API 密钥的有效实施需要在使用前用新的密钥重新配置。

承载访问令牌

要获取承载访问令牌，请与您的 client_id 和 client_secret 一起使用Content-Type: application/x-www-form-urlencoded 向验证端点发送 POST 请求。当使用用于组织管理的 API 时，您将始终使用 grant_type=client_credentials 和 scope=api.organization。例如：

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>'

该请求将返回如下响应：

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

在此响应中，3600 表示到期值（以秒为单位），表示此令牌在发出后 60 分钟内有效。使用过期的令牌进行 API 调用将返回一个 401 未经授权 的响应代码。

内容类型

Bitwarden Public API 与 application/json 请求和响应进行通信，但有一个例外：验证端点期望一个 application / x-www-form-urlencoded 请求时，将只以 application/json 响应。

样本请求

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

这里的 <TOKEN> 表示 access_token 的值：获取到的承载访问令牌中的值。

该请求将返回如下响应：

{
  "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 拥有一个公共状态页面，您可以在其中查看所有服务（包括公共 API）的运行状况和事件的信息。

响应代码

状态代码描述

状态代码	描述
`200 OK`	一切都按预期进行。
`400 Bad Request`	该请求不可接受。可能是由于参数丢失或格式错误。
`401 Unauthorized`	承载访问令牌丢失、无效或过期。
`404 Not Found`	所请求的资源不存在。
`429 Too Many Requests`	太多请求太快到达 API。我们建议缩减请求数。
`500, 502, 503, 504 Server Error`	Bitwarden 端出现问题。这些情况很少见，如果发生，请与我们联系。

200 OK

一切都按预期进行。

400 Bad Request

该请求不可接受。可能是由于参数丢失或格式错误。

401 Unauthorized

承载访问令牌丢失、无效或过期。

404 Not Found

所请求的资源不存在。

429 Too Many Requests

太多请求太快到达 API。我们建议缩减请求数。

500, 502, 503, 504 Server Error

Bitwarden 端出现问题。这些情况很少见，如果发生，请与我们联系。

进一步阅读

有关使用 Bitwarden Public API 的更多信息，请参阅以下文章：

最后更新于6个月前