Bitwarden 公共 API

对应的官方文档地址

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

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

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

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

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

Swagger 官方网站Swagger 介绍 1Swagger 介绍 2Swagger 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_idclient_secret 作为必要的参数。client_idclient_secret 可以由所有者从网页密码库获得,方法是导航到设置选项卡 → 我的组织,并向下滚动到 API 密钥部分。

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

承载访问令牌

要获取承载访问令牌,请与您的 client_idclient_secret 一起使用Content-Type: application/x-www-form-urlencoded验证端点发送 POST 请求。当使用用于组织管理的 API 时,您将始终使用 grant_type=client_credentialsscope=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 端出现问题。这些情况很少见,如果发生,请与我们联系

进一步阅读

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