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）的运行状况和事件的信息。

响应代码

状态代码

描述

进一步阅读

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

最后更新于1年前