# API 与客户端库

> 通过您自己的代码创建、获取和销毁内容。区域基础 URL、身份验证、curl 快速开始，以及官方和社区客户端库。

网页应用对内容执行的所有操作都可以通过 HTTPS 和 JSON 完成。常见的模式是由脚本或流水线创建一条内容，再把链接交给某个人，这样凭据就永远不会留在日志、工单或聊天记录中。

完整的端点参考（包含请求和响应模式以及在线试用控制台）位于 **[api.onetimesecret.com](https://api.onetimesecret.com)**。本页介绍在打开它之前您需要了解的内容。

## 基础 URL

请求发送到保存您账户的区域。每个区域都是独立的部署，区域之间不会复制任何数据。

```plaintext
https://REGION.onetimesecret.com/api/v2
```

| `REGION` | 主机                 |
| -------- | ---------------------- |
| `ca`     | `ca.onetimesecret.com` |
| `eu`     | `eu.onetimesecret.com` |
| `nz`     | `nz.onetimesecret.com` |
| `uk`     | `uk.onetimesecret.com` |
| `us`     | `us.onetimesecret.com` |

不带区域前缀的 `onetimesecret.com` 主机仍会响应 API 请求并路由到一个活跃区域，但请明确固定一个区域，这样即使该回退机制停用，您的集成也能继续工作。有关每个区域对您数据的意义，请参阅[您的数据存放在哪里](/en/security/where-your-data-lives/)。

在[自定义域名](/zh-cn/custom-domains/)上，API 位于您域名下的相同路径，它创建的链接也会使用该域名：

```plaintext
https://secrets.example.com/api/v2
```

[自托管](/zh-cn/self-hosting/)实例会在您运行它的任何主机上提供相同的 API。

## 身份验证

使用 HTTP Basic 身份验证。用户名是您的账户邮箱，密码是账户设置中的 API 令牌。

```bash
curl -u 'you@example.com:APITOKEN' https://eu.onetimesecret.com/api/v2/status
```

创建和查看内容在不进行身份验证的情况下也可以使用，但会受到匿名用户的限制：最长有效期更短、内容大小更小，并且没有回执列表。经过身份验证的请求适用您方案的限制，并会出现在您的[回执](/en/share/your-receipt/)中。

## 快速开始

创建一条有效期为一小时的内容：

```bash
curl -u 'you@example.com:APITOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"secret": {"secret": "the password is hunter2", "ttl": 3600}}' \
  https://eu.onetimesecret.com/api/v2/secret/conceal
```

响应包含两条记录。`record.secret.identifier` 是您分享的密钥，形式为 `https://eu.onetimesecret.com/secret/IDENTIFIER`。`record.receipt.identifier` 则属于您自己：它显示内容是否已被查看，并允许您提前销毁它。切勿将回执密钥发送给收件人。

在 `secret` 对象中添加 `"passphrase": "..."` 即可要求在查看时输入口令。口令是一项访问检查，而不是加密密钥：服务只存储口令的单向哈希值，并在解密值之前对其进行检查。口令丢失后无法找回，此后该内容既无法查看也无法销毁，会在过期时被删除。

查看一条内容（查看后即失效）：

```bash
curl -X POST -H 'Content-Type: application/json' -d '{}' \
  https://eu.onetimesecret.com/api/v2/secret/IDENTIFIER/reveal
```

使用回执密钥，在任何人查看之前销毁一条内容：

```bash
curl -u 'you@example.com:APITOKEN' -X POST \
  https://eu.onetimesecret.com/api/v2/receipt/RECEIPT_IDENTIFIER/burn
```

## API 版本

* **v2** 是当前的公开 API：JSON 输入和输出、回执、状态和销毁端点。请基于此版本构建。
* **v1** 是最初的表单编码 API（`POST /api/v1/share`）。它仍然可用，大多数社区库也在使用它，但新的集成应使用 v2。

两者均在 [api.onetimesecret.com](https://api.onetimesecret.com) 有文档说明。

## 客户端库

[客户端库](/zh-cn/api/client-libraries/)官方 SDK 和社区库，并附有关于哪些库支持 API v2、区域和自定义域名的说明。

[完整 API 参考](https://api.onetimesecret.com)v1 和 v2 的每个端点、请求和响应模式，以及可针对您的账户试用调用的控制台。

## 相关内容

* [您的数据存放在哪里](/en/security/where-your-data-lives/)：选择区域，以及哪些数据留在区域内。
* [自定义域名](/zh-cn/custom-domains/)：在您自己的域名上使用一次性链接和 API 访问。
* [自托管](/zh-cn/self-hosting/)：在您自己的基础设施上运行 API。
* [开发者入门](/en/contribute/developer-on-ramp/)：在本地运行应用程序并参与贡献。