# 获取密钥

> 如何申请一把合作方 API 密钥、申请里要写什么，以及会拿到什么。

Source: https://developers.backresto.com/zh/docs/access

合作方密钥由人工签发。填写下面的表单（或者给我们发邮件，两条路到达的是同一批
人），我们会开通这份凭据，并把它发给你指定的联系人。

每一份申请都有人在读，因为一把密钥意味着能访问一家餐厅的合规记录，而餐厅必须
已经同意。它让你付出的是一次回复而不是一次跳转；换来的是没有人能给自己凭空造出
访问别人数据的权限。表单会一次问全我们据以行动所需要的一切。

## 谁可以申请

哪一边都可以，但无论哪一边，餐厅都得同意。

- **你，集成方。** 说明你需要哪些餐厅，并点出你在那边的联系人；在签发任何东西
  之前，我们会与他们确认。
- **餐厅。** 他们代表你提出申请并点名你。这条路更快，因为确认已经发生过了。

我们不会为一家没有同意的餐厅签发密钥，也不会在没有再次征询他们意见的情况下扩大
一把已有的密钥。

## 申请一把密钥

To request a key, write to contact@backresto.com or fill in the form at https://developers.backresto.com/zh/docs/access. Name the company, the product that will call the API, a technical contact, the restaurants and the scopes you need.

如果你要为分属不同客户的多家餐厅做集成，请每个客户发一份申请。一个客户一把密钥，
能让一次吊销不至于把你运行的其他集成一起拖垮。

其中两个字段值得说一句。**环境**之所以重要，是因为密钥和数据都是按环境分开的：
一把生产环境的密钥在预生产环境里毫无意义，所以如果你想先在预生产环境上开发，
请说明。而**权限范围**应该是你用得上的那些，而不是全都要：一共有二十六个，每个
[集合](https://developers.backresto.com/zh/docs/collections)一个，收货记录和它们的照片也包括在内，而且餐厅会在同意之前
读一遍这份清单。点名你需要的那四个，比把它们全要过来更快得到一个「好」；看
[认证](https://developers.backresto.com/zh/docs/authentication) 了解每一个权限范围打开的是什么。

已经持有一把密钥，却想要一个它触及不到的集合？还是同一封邮件，而且这是一次扩展
而不是一把新密钥：你的密钥串不变，也不需要重新部署任何东西。

更想自己写封邮件？[contact@backresto.com](mailto:contact@backresto.com?subject=Partner%20API%20key%20request)
附上同样的细节，到达的是同一个收件箱。

## 会拿到什么

一个单独的值，形如 `brp_<prefix>.<secret>`，发送给你指定的技术联系人。

**到手就存好，然后删掉那封邮件。** 我们只保存公开前缀和密钥串的摘要，因此我们
无法重发。如果它丢了，我们会吊销那把密钥并签发一把新的，那就意味着又一趟往返。

密钥不会自己过期。它们在被吊销之前一直有效，这也是为什么「有人离职了」的答案是
一次轮换，而不是耸耸肩。

## 日后变更一把密钥

下面这些都是一封邮件的事，而其中凡是扩大了访问范围的，都需要餐厅同意：

| 诉求 | 会发生什么 |
| --- | --- |
| **增加一家餐厅或一个权限范围** | 我们扩展这把已有的密钥。你的密钥串不变，也不需要重新部署任何东西。 |
| **轮换** | 我们先签发第二把密钥，你把它部署上去，然后我们吊销旧的那把。不存在两把都不能用的窗口。 |
| **吊销** | 立即生效。下一个带着那把密钥的请求返回 `401`。 |
| **一把限时密钥** | 在申请里说明。对于一次性审计或概念验证，一把会自己失效的密钥，比一把要你记着去关掉的更安全。 |

任何紧急情况（尤其是密钥串泄露），请写信到
[contact@backresto.com](mailto:contact@backresto.com?subject=Urgent%3A%20revoke%20Partner%20API%20key)，
附上这把密钥的**公开前缀**（点号前 `brp_…` 的那一半），并说明这是紧急事项。绝不要
把密钥串本身发给我们，哪怕只是为了说明你指的是哪一把。

## 等待期间

[文档](https://developers.backresto.com/zh/docs)里没有任何内容需要密钥才能阅读，各种数据结构也都在这些页面上：
[收货记录及其照片](https://developers.backresto.com/zh/docs/deliveries)、[集合与记录](https://developers.backresto.com/zh/docs/collections)、
[错误模型](https://developers.backresto.com/zh/docs/errors)和[分页](https://developers.backresto.com/zh/docs/pagination)。
[OpenAPI 文档](https://api.backresto.com/openapi.json) 同样是公开的，所以你可以在
密钥到达之前就生成一个客户端并对着它写代码。