服务端凭据与 IP 白名单
业务服务端调用服务端 REST API（OpenAPI）之前，要先用应用的 Client ID 和 Client Secret 换取 App Token，见鉴权与 App Token。本页介绍如何在控制台中查看、轮换和吊销这组凭据，以及如何用 IP 白名单限制哪些服务器可以调用 OpenAPI。
凭据在应用详情的“服务端密钥”标签页中管理，IP 白名单在“IP 白名单”标签页中管理。所有成员都可以查看，修改需要 owner 或 admin。
凭据与槽位
创建应用时，系统生成第一组凭据，Client Secret 只在创建时显示一次，见创建应用。之后控制台中不再显示 Secret 的完整内容，只显示前几个字符，便于辨认是哪一个。
每个应用有两个槽位：primary 和 secondary，每个槽位同时最多有一个有效的 Secret，所以一个应用同时最多有两个有效的 Secret。两个槽位的作用相同，有两个是为了不停机地更换 Secret：新旧 Secret 可以在一段时间内同时有效。系统生成的凭据，同一个应用的 Client ID 固定不变，轮换只更换 Secret。
“服务端密钥”中的凭据列表：
| 列 | 说明 |
|---|---|
| client_id | 换取 App Token 时使用的 Client ID |
| 密钥前缀 | Secret 的前几个字符：系统生成的显示前 8 个，导入的只显示前 4 个 |
| 槽位 | primary 或 secondary |
| 来源 | 生成：由系统生成；导入：从其他厂商迁移时导入 |
| 状态 | 有效、已吊销或已过期。只有有效的 Secret 可以换取 App Token |
| 到期 | 有效的 Secret 到这个时间自动失效；“永久”表示不会自动失效 |
| 最近使用 | 最近一次用它换取 App Token 的时间，最多每小时更新一次，可以据此判断旧 Secret 是否还在使用 |
| 创建时间 | Secret 的创建时间 |
轮换密钥
定期更换 Secret，或者怀疑 Secret 泄露时，可以轮换。owner 或 admin 在“服务端密钥”中点击“轮换密钥”，按提示重新验证身份：
- 系统在空闲的槽位生成一个新的 Secret，立即生效。页面显示新的 client_id 和 client_secret，client_secret 只显示这一次，保存后点击“我已保存”；
- 另一个仍然有效的 Secret 进入 24 小时的宽限期：宽限期内新旧 Secret 都能换取 App Token，到期后旧 Secret 自动失效，它换取的 App Token 也随之失效。
不停机更换 Secret 的步骤：
- 点击“轮换密钥”，保存新的 Secret；
- 把业务服务端的配置更新为新的 Secret，用它换取新的 App Token；
- 在凭据列表中确认旧 Secret 的“最近使用”不再变化后，点击它的“吊销”，或者等宽限期结束自动失效。
两个槽位都有有效的 Secret 时不能轮换，页面提示“两个密钥槽位都已占用，请先吊销一个”。请先确认哪一个不再使用，吊销它之后再轮换。
吊销密钥
owner 或 admin 可以点击有效 Secret 那一行的“吊销”，按提示重新验证身份。吊销后：
- 这个 Secret 立即不能再换取 App Token；
- 用它换取的 App Token 也立即失效，调用 OpenAPI 返回
401 unauthenticated；用另一个 Secret 换取的 App Token 不受影响； - 如果另一个 Secret 正处于宽限期，它的宽限期被取消，变为长期有效，避免宽限期结束后应用没有可用的 Secret。
应用最后一个有效的 Secret 不能吊销，页面提示“不能吊销最后一个有效的密钥”；需要更换时请先轮换。
怀疑 Secret 泄露时
立即轮换出新的 Secret，把服务端切换到新 Secret 后吊销旧的。吊销会让旧 Secret 换取的全部 App Token 失效，泄露的凭据随即无法使用。同时建议配置下文的 IP 白名单。
导入其他厂商的凭据
从其他 IM 服务迁移过来时，如果你的业务服务端中已经配置了原来的 Client ID 和 Client Secret，可以把它们导入应用，继续用原来的凭据换取 App Token，不必重新分发凭据。
- 导入的 Client ID 和 Secret 都保持原样，占用一个空闲的槽位；两个槽位都被占用时要先吊销一个；
- Client ID 为 1 到 128 个字符，Secret 为 16 到 256 个字符，都只能包含不含空格的可见 ASCII 字符；
- Secret 导入后同样不能再查看，凭据列表中只显示它的前 4 个字符；
- 导入需要
owner或admin，并且要重新验证身份。导入的凭据可以像其他凭据一样吊销。
导入只保留凭据本身：org_name 由系统生成，AppKey 和 OpenAPI 的地址都会变化，服务端和客户端仍需改用新的地址和 AppKey。
控制台中的入口
控制台的“服务端密钥”页面目前只提供轮换和吊销，导入入口即将开放。迁移时需要保留原来的凭据，请联系我们。
IP 白名单
IP 白名单限制哪些来源 IP 可以换取 App Token 和调用 OpenAPI。配置后，即使凭据泄露，其他地方的服务器也无法调用。建议把业务服务端的公网出口 IP 都加入白名单。
- 只限制服务端：白名单只检查换取 App Token 和 OpenAPI 请求的来源 IP，不影响客户端（App、网页）登录和收发消息，也不影响控制台；
- 没有生效的条目时不限制：应用没有任何生效中的条目（已启用、已到生效时间且没有过期）时，允许所有 IP 调用；
- 有生效的条目时只放行白名单：只要有一个条目生效，来源 IP 不在任何生效条目中的请求都返回
403 ip_not_allowed。
在“IP 白名单”标签页中点击“添加”，填写：
| 字段 | 说明 |
|---|---|
| IP 或网段 | 单个 IP，如 203.0.113.10、2001:db8::10；或 CIDR 格式的网段，如 203.0.113.0/24、2001:db8::/32 |
| 说明 | 可选，最多 256 个字符，如“生产环境出口” |
| 到期时间 | 可选，到这个时间后条目不再生效，适合临时放开某个地址；不填则长期有效 |
添加时会规范化填写的地址：单个 IP 保存为 /32（IPv6 为 /128）的网段，网段去掉主机位（如 203.0.113.77/24 保存为 203.0.113.0/24），IPv4 映射的 IPv6 地址（如 ::ffff:198.51.100.9）按 IPv4 保存。同一个网段不能重复添加；网段添加后不能修改，需要修改时删除后重新添加。
列表中每个条目可以：
- 启用：关闭开关后条目暂时不生效，不必删除；
- 删除：条目立即移除。
列表中的“生效”和“到期”两列是条目的生效时间和过期时间：在控制台中添加的条目立即生效，“生效”一列显示为 -；“到期”为“永久”表示长期有效。过期的条目不会自动删除，但不再生效。
修改白名单后，换取 App Token 立即按新的白名单检查，其他 OpenAPI 请求最迟 30 秒后生效。每个应用最多 200 个条目（包括已停用和已过期的），超出时请删除不再需要的条目。
添加第一个条目前
第一个条目生效后，白名单之外的服务器立刻无法调用 OpenAPI。添加前请确认业务服务端全部的出口 IP，包括多台服务器、NAT 网关和代理的地址；从本机调试时，记得把调试机器的出口 IP 也加进去，或者使用单独的测试应用。