服務端憑據與 IP 白名單
業務服務端呼叫服務端 REST API（OpenAPI）之前，要先用應用的 Client ID 和 Client Secret 換取 App Token，見鑑權與 App Token。本頁介紹如何在控制檯中檢視、輪換和吊銷這組憑據，以及如何用 IP 白名單限制哪些伺服器可以呼叫 OpenAPI。
憑據在應用詳情的“服務端金鑰”標籤頁中管理，IP 白名單在“IP 白名單”標籤頁中管理。所有成員都可以檢視，修改需要 owner 或 admin。
憑據與槽位
建立應用時（包括註冊時自動建立的 demo 應用），系統生成第一組憑據，見建立應用。控制檯的列表中只顯示 Secret 的前幾個字元，便於辨認是哪一個；所有成員都可以在概覽的“接入憑證”中點選“檢視”，重新驗證身份後再次檢視當前生效的 Secret 的完整內容。較早建立、沒有儲存可恢復密文的 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，請立即儲存到服務端，然後點選“我已儲存”。之後可以在概覽中再次檢視；
- 另一個仍然有效的 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 也加進去，或者使用單獨的測試應用。