API 与客户端库

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

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

基础 URL

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

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 请求并路由到一个活跃区域，但请明确固定一个区域，这样即使该回退机制停用，您的集成也能继续工作。有关每个区域对您数据的意义，请参阅您的数据存放在哪里。

在自定义域名上，API 位于您域名下的相同路径，它创建的链接也会使用该域名：

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

自托管实例会在您运行它的任何主机上提供相同的 API。

身份验证

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

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

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

快速开始

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

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

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

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

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

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 有文档说明。

客户端库

客户端库官方 SDK 和社区库，并附有关于哪些库支持 API v2、区域和自定义域名的说明。

完整 API 参考v1 和 v2 的每个端点、请求和响应模式，以及可针对您的账户试用调用的控制台。