# 登记客户端

> 理事会成员如何在“开发者”页面登记一个集成，选择哪种类型，以及究竟需要登记哪些内容。

URL: https://developers.vimine.network/zh-hans/start/register-a-client/

每个集成都是一个**客户端**，在 Vimine 应用的**开发者**页面中登记。该页面仅供协会理事会使用：如果您不是理事会成员，请找一位理事会成员为您登记客户端，并把登录凭据交给您。

没有协会——代理机构、插件开发者、想试用 API 的人——可以向平台申请**开发者邀请**：您将拥有一个属于自己的[沙盒](https://developers.vimine.network/zh-hans/guides/sandbox/)，即一个有虚构会员的测试协会，并在其中自行登记测试客户端，同时接受开发者条款。生产客户端仍归您为之工作的协会所有。

## 客户端类型

| 类型 | 用于 | 凭据 | 说明 |
|---|---|---|---|
| **网站**（公开） | 浏览器中的页面 | 仅 `client_id` | 必须使用 PKCE；`https` 重定向 URI 须完全一致 |
| **原生应用** | 移动或桌面应用 | 仅 `client_id` | 同上；使用回环地址重定向（`http://127.0.0.1:{port}/…`）或自定义协议 |
| **服务器**（机密） | 协会的后端系统 | `client_id` + `client_secret` | secret 只显示一次；绝不能出现在浏览器中 |

公开客户端和原生客户端实现**使用 Vimine 登录**，并以会员的令牌调用 API。机密客户端还可以自行认证（`client_credentials`），以使用“客户端”权限，例如读取会员卡状态。

## 环境

| 环境 | 位于何处 | 何时生效 |
|---|---|---|
| **测试** | 在协会的[沙盒](https://developers.vimine.network/zh-hans/guides/sandbox/)中（按需创建） | **立即** |
| **生产** | 在真实协会中 | 由 Vimine 开通之后：您会收到一封电子邮件 |

测试客户端签发的令牌带有 `mode: "test"`，无法触及真实协会。它们的机密凭据以 `vms_test_` 开头。

## 需要登记的内容

1. **名称**——会员将在授权同意页面上看到的名称（“*名称*想要访问您的个人资料……”）。
2. **类型**和**环境**。
3. **重定向 URI**——登录后 Vimine 可以把浏览器送回的页面。匹配是**完全一致**的（协议、主机、端口、路径）：请登记您将使用的每一个回调页面。
4. **允许的来源**——您的页面在浏览器中调用 API 时所在的来源（`https://www.example.org`）。它们用于 CORS，也是退出登录后允许跳转的目标（`post_logout_redirect_uri`）。
5. **权限**——该集成可以申请的 scope。只申请您需要的：会员会看到全部权限。公开客户端或原生客户端只能拥有会员权限；“客户端”权限需要机密客户端。列表见[权限、错误与限制](https://developers.vimine.network/zh-hans/guides/scopes-and-errors/)。

创建时您会获得 `client_id`（`vmc_…`），机密客户端还会获得 `client_secret`（`vms_…`），它**只显示一次**。对于测试客户端，页面还会显示沙盒中的虚构会员及其密码。

## 生命周期

- **重新生成 secret**——新的 secret 只显示一次；**旧的 secret 继续有效 24 小时**，因此您可以在不中断服务的情况下更新系统。
- **暂停**——客户端的令牌停止工作，直到您将它恢复。是否恢复由理事会决定。
- **撤销**——不可逆：该客户端的所有会话立即结束，会员在自己的已连接应用中也不再看到它。
- 会员可以随时在个人中心的**已连接的应用**中撤回同意：该客户端针对该会员的会话随即结束。

:::tip[本地开发]
**测试**客户端可以使用 `http://localhost:…` 形式的重定向 URI 和来源：这是正常的开发方式。生产环境中只能使用 `https`（原生应用的回环地址除外）。
:::