使用 Glossia 登录

本指南将指导您为您的应用添加“使用 Glossia 登录”。到本指南结束时，您的用户将能够使用其 Glossia 账户登录，且您的应用将获得访问令牌，以便代表他们调用 Glossia API。

Glossia 使用 带有 PKCE 的 OAuth 2.1 (代码交换证明密钥)。PKCE 对所有客户端都是必需的，包括服务器端应用程序。

1. 注册您的 OAuth 应用

您有两种注册应用程序的选项：

选项 A：通过仪表盘（推荐）

1. 登录 Glossia 并进入您的账户仪表盘。
2. 打开 API 侧边栏中的部分并点击 OAuth 应用。
3. 点击 新应用。
4. 填写应用 名称 和 回调 URL (也称为重定向 URI)。
5. 点击 创建应用。

创建后，记下 客户端 ID 和 客户端密钥。密钥仅显示一次，请务必安全保存。

选项 B：动态客户端注册

发送一个 POST 请求至 /oauth/register：

curl -X POST https://glossia.ai/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My App",
    "redirect_uris": ["https://myapp.com/auth/callback"],
    "grant_types": ["authorization_code"]
  }'

响应包含 client_id 与 client_secret.

2. 生成 PKCE 代码挑战

在重定向用户之前，生成 PKCE 代码验证器与挑战：

function generateCodeVerifier() {
  const array = new Uint8Array(32);
  crypto.getRandomValues(array);
  return btoa(String.fromCharCode(...array))
    .replace(/\+/g, "-")
    .replace(/\//g, "_")
    .replace(/=+$/, "");
}

async function generateCodeChallenge(verifier) {
  const encoder = new TextEncoder();
  const data = encoder.encode(verifier);
  const digest = await crypto.subtle.digest("SHA-256", data);
  return btoa(String.fromCharCode(...new Uint8Array(digest)))
    .replace(/\+/g, "-")
    .replace(/\//g, "_")
    .replace(/=+$/, "");
}

const codeVerifier = generateCodeVerifier();
const codeChallenge = await generateCodeChallenge(codeVerifier);
// Store codeVerifier in your session -- you will need it in step 4

3. 将用户重定向到 Glossia

构建授权 URL 并重定向用户浏览器：

https://glossia.ai/oauth/authorize?
  response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://myapp.com/auth/callback
  &code_challenge=YOUR_CODE_CHALLENGE
  &code_challenge_method=S256
  &scope=user:read+project:read
  &state=RANDOM_STATE_VALUE

参数：

用户将看到一个同意界面，显示您的应用名称和请求的作用域。获得批准后，Glossia 会重定向回您的回调 URL 并附带授权码。

4. 使用代码交换令牌

当用户被重定向回您的回调 URL 时，该 URL 将包含一个 code 参数：

https://myapp.com/auth/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE_VALUE

首先，验证 state 与您在第 3 步中发送的内容一致。然后兑换代码以获取令牌：

curl -X POST https://glossia.ai/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://myapp.com/auth/callback" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "code_verifier=YOUR_CODE_VERIFIER"

响应：

{
  "access_token": "eyJhbGciOiJSUzI1...",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBhIHJl..."
}

请安全地存储这两个令牌。访问令牌用于 API 请求。刷新令牌用于在当前访问令牌过期时获取新的访问令牌。

5. 代用户调用 API

使用访问令牌发起身份验证的 API 请求：

curl -H "Authorization: Bearer eyJhbGciOiJSUzI1..." \
  https://glossia.ai/api/projects

令牌范围限制了您可以访问的端点。资源级授权仍然适用 - 例如，一个具有 project:read 仅能读取用户有权访问的项目。

6. 刷新令牌

当访问令牌过期时，请使用刷新令牌获取新令牌，而无需再次引导用户经过同意流程：

curl -X POST https://glossia.ai/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=dGhpcyBpcyBhIHJl..." \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

7. 撤销令牌

当用户断开您的应用或您不再需要访问权限时，请撤销令牌：

curl -X POST https://glossia.ai/oauth/revoke \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=eyJhbGciOiJSUzI1..." \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

选择作用域

仅请求您的应用程序所需的作用域。以下是一些常见组合：

查看 完整作用域参考 适用于所有可用范围。

发现端点

您的应用程序可以通过获取服务器元数据自动发现 Glossia 的 OAuth 端点：

curl https://glossia.ai/.well-known/oauth-authorization-server

此返回一个 JSON 文档，包含以下 authorization_endpoint重新组装的文档之前验证失败：Markdown 文本字面量恢复返回了无效 JSON token_endpoint重新组装的文档此前验证失败：Markdown 文本字面量恢复必须返回匹配长度的 JSON 字符串数组 revocation_endpoint，以及其他详细信息。使用发现可使您的集成对端点变更具有弹性。

错误处理

授权错误

如果用户拒绝同意或授权过程中出现问题，Glossia 会将您重定向到回调 URL 并附带一个 error 参数：

https://myapp.com/auth/callback?error=access_denied&state=RANDOM_STATE_VALUE

常见错误代码：

令牌错误

令牌端点返回 HTTP 400 并包含 JSON 错误内容：

{
  "error": "invalid_grant",
  "error_description": "The authorization code has expired or was already used."
}

速率限制

OAuth 端点按 IP 限制速率。若触发限制，将收到 HTTP 429。查阅 限流参考 详情。

安全检查表

在生产部署前，请确认您的实现遵循以下实践：

• 生产环境回调 URL 必须始终使用 HTTPS
• 验证 state 回调中的参数以防止 CSRF
• 静态加密存储令牌
• 切勿在客户端 JavaScript 或浏览器 URL 中暴露令牌
• 使用所需的最小作用域集合
• 使用刷新令牌优雅地处理令牌过期
• 当用户断开连接或删除账户时撤销令牌