wildix-auth

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Wildix Authentication

Wildix 身份验证

Authenticates users with Wildix apps (Collaboration 7, x-bees, x-hoppers) via AWS Cognito CUSTOM_AUTH. Tokens stored per-email in

<BASE_DIR>/tokens/

通过AWS Cognito CUSTOM_AUTH对Wildix应用（Collaboration 7、x-bees、x-hoppers）的用户进行身份验证。令牌按邮箱存储在

<BASE_DIR>/tokens/

目录下。

Which Token to Use

应使用哪种令牌

Use
IdToken
for all Wildix API calls (not AccessToken). Expires in 1 hour.

Always retrieve it via

get-token.sh

— auto-refreshes when expired, validates via API after refresh:

bash

ID_TOKEN=$(bash <BASE_DIR>/scripts/get-token.sh "<email>" "<BASE_DIR>")

Exit code 2 = token rejected by API → go to Mode 2 (re-auth).

**使用

IdToken

**进行所有Wildix API调用（不要使用AccessToken）。有效期为1小时。

请始终通过

get-token.sh

获取令牌——令牌过期时会自动刷新，刷新后会通过API验证有效性：

bash

ID_TOKEN=$(bash <BASE_DIR>/scripts/get-token.sh "<email>" "<BASE_DIR>")

退出码2表示令牌被API拒绝 → 切换到模式2（重新认证）。

Mode 1: Get a Valid Token (tokens already exist)

模式1：获取有效令牌（令牌已存在）

1. Determine email

1. 确定邮箱

List authenticated sessions:

bash

ls <BASE_DIR>/tokens/*.json 2>/dev/null | xargs -I{} jq -r '.email' {} 2>/dev/null

0 sessions → go to Mode 2
1 session → use it
2+ sessions → use
```
AskUserQuestion
```
to ask which email to use; include "Add new" as option

列出已认证的会话：

bash

ls <BASE_DIR>/tokens/*.json 2>/dev/null | xargs -I{} jq -r '.email' {} 2>/dev/null

0个会话 → 切换到模式2
1个会话 → 使用该会话对应的邮箱
2个及以上会话 → 使用
```
AskUserQuestion
```
询问用户使用哪个邮箱；提供“添加新邮箱”选项

2. Get valid IdToken

2. 获取有效的IdToken

bash

ID_TOKEN=$(bash <BASE_DIR>/scripts/get-token.sh "<email>" "<BASE_DIR>")

bash

ID_TOKEN=$(bash <BASE_DIR>/scripts/get-token.sh "<email>" "<BASE_DIR>")

Mode 2: Authenticate (new session or re-auth)

模式2：身份验证（新会话或重新认证）

1. Ask for email

1. 请求用户提供邮箱

If email is unknown, use

AskUserQuestion

如果邮箱未知，使用

AskUserQuestion

询问。

2. Initiate auth — sends code to email

2. 启动认证流程——向邮箱发送验证码

bash

bash <BASE_DIR>/scripts/initiate-auth.sh "<email>" | tee /tmp/wildix_auth_session.txt

bash

bash <BASE_DIR>/scripts/initiate-auth.sh "<email>" | tee /tmp/wildix_auth_session.txt

3. Ask user for the code

3. 请求用户提供验证码

Use

AskUserQuestion

(user types code via "Other"):

"A verification code was sent to <email>. Enter the code (use 'Other' to type it):"

使用

AskUserQuestion

（用户通过“其他”选项输入验证码）：

“验证码已发送至<email>。请输入验证码（选择‘其他’进行输入）：”

4. Complete auth

4. 完成认证

bash

SESSION=$(cat /tmp/wildix_auth_session.txt)
bash <BASE_DIR>/scripts/respond-auth.sh "<email>" "$SESSION" "<CODE>" "<BASE_DIR>"

bash

SESSION=$(cat /tmp/wildix_auth_session.txt)
bash <BASE_DIR>/scripts/respond-auth.sh "<email>" "$SESSION" "<CODE>" "<BASE_DIR>"

5. Return token

5. 返回令牌

bash

ID_TOKEN=$(bash <BASE_DIR>/scripts/get-token.sh "<email>" "<BASE_DIR>")

bash

ID_TOKEN=$(bash <BASE_DIR>/scripts/get-token.sh "<email>" "<BASE_DIR>")

Token File Format

令牌文件格式

<BASE_DIR>/tokens/<sanitized_email>.prod.json

(

→

_at_

, e.g.

user_at_wildix.com.prod.json

)

json

{
  "email": "user@wildix.com",
  "AccessToken": "...",
  "IdToken": "...",
  "RefreshToken": "...",
  "ExpiresIn": 3600,
  "savedAt": "2026-01-01T00:00:00Z"
}

<BASE_DIR>/tokens/<sanitized_email>.prod.json

（

替换为

_at_

，例如

user_at_wildix.com.prod.json

）

json

{
  "email": "user@wildix.com",
  "AccessToken": "...",
  "IdToken": "...",
  "RefreshToken": "...",
  "ExpiresIn": 3600,
  "savedAt": "2026-01-01T00:00:00Z"
}

Mode 3: Logout / Revoke Access

模式3：登出 / 撤销访问权限

Trigger this mode when the user asks to: log out, sign out, remove authorization, delete a session, revoke access, or suspects a token was leaked.

当用户要求登出、退出、取消授权、删除会话、撤销访问权限，或怀疑令牌泄露时，触发此模式。

1. Determine which email to log out

1. 确定要登出的邮箱

bash

ls <BASE_DIR>/tokens/*.json 2>/dev/null | xargs -I{} jq -r '.email' {} 2>/dev/null

If multiple sessions exist, ask which one using

AskUserQuestion

bash

ls <BASE_DIR>/tokens/*.json 2>/dev/null | xargs -I{} jq -r '.email' {} 2>/dev/null

如果存在多个会话，使用

AskUserQuestion

询问用户要登出哪个邮箱。

2. Ask the user which type of logout

2. 询问用户登出类型

Use

AskUserQuestion

with these two options:

This device only — revokes the current refresh token; other active sessions on other devices remain valid
All devices (global sign-out) — invalidates ALL active sessions everywhere (x-bees web, mobile, other agents); the user will need to re-authenticate on every device

Make sure the user understands the consequences before proceeding.

使用

AskUserQuestion

提供以下两个选项：

仅当前设备 —— 撤销当前刷新令牌；其他设备上的活跃会话保持有效
所有设备（全局登出） —— 使所有位置的所有活跃会话失效（x-bees网页端、移动端、其他代理）；用户需要在所有设备上重新认证

请确保用户了解后果后再继续。

3a. This device only

3a. 仅当前设备

bash

bash <BASE_DIR>/scripts/revoke-token.sh "<email>" "<BASE_DIR>"

Revokes the refresh token on Cognito and deletes the local token file.

bash

bash <BASE_DIR>/scripts/revoke-token.sh "<email>" "<BASE_DIR>"

在Cognito上撤销刷新令牌，并删除本地令牌文件。

3b. All devices (global sign-out)

3b. 所有设备（全局登出）

Before running, confirm with
AskUserQuestion
:

"Global sign-out will immediately invalidate ALL active sessions for
<email>
— x-bees web, mobile app, all other agents and devices. You will need to re-authenticate everywhere. Are you sure?"

Options: Yes, sign out everywhere / Cancel

Only proceed if the user confirms. If cancelled — do nothing and inform the user.

bash

bash <BASE_DIR>/scripts/global-signout.sh "<email>" "<BASE_DIR>"

Calls Cognito

GlobalSignOut

using the AccessToken — invalidates all sessions for the account — and deletes the local token file.

Note:
GlobalSignOut
requires a non-expired AccessToken. If the local token is expired (>1h old), run
get-token.sh
first to refresh it, then run
global-signout.sh
.

执行前，使用
AskUserQuestion
确认：

“全局登出将立即使
<email>
的所有活跃会话失效——包括x-bees网页端、移动端应用、所有其他代理和设备。你需要在所有位置重新认证。确定要继续吗？”

选项：是，全部登出 / 取消

仅在用户确认后执行。如果用户取消——不执行任何操作并告知用户。

bash

bash <BASE_DIR>/scripts/global-signout.sh "<email>" "<BASE_DIR>"

使用AccessToken调用Cognito的

GlobalSignOut

——使该账户的所有会话失效——并删除本地令牌文件。

注意：
GlobalSignOut
需要未过期的AccessToken。如果本地令牌已过期（超过1小时），请先运行
get-token.sh
刷新令牌，再运行
global-signout.sh
。

Common Mistakes

常见问题

Problem	Fix
Using AccessToken instead of IdToken	Always use IdToken for Wildix API
Not checking expiry before API call	Use `get-token.sh` — handles refresh + validation automatically
Wrong code or expired session	Re-run Mode 2 step 2 (Cognito session valid ~10 min)
`jq` not installed	`brew install jq`

问题	解决方法
使用AccessToken而非IdToken	始终使用IdToken进行Wildix API调用
API调用前未检查令牌有效期	使用 `get-token.sh` ——它会自动处理令牌刷新和有效性验证
验证码错误或会话过期	重新执行模式2的步骤2（Cognito会话有效期约10分钟）
未安装 `jq`	执行 `brew install jq` 安装