#身份验证服务 REST API 参考

本文档描述了身份验证服务API。

版本：1.25.0
基础URL：{{API_BASE_URL}}/api/v2/auth
方案：HTTPS

#端点

1. 获取JSON Web 密钥集(JWKS)
2. 获取OpenID配置
3. 创建代理
4. 强制注销用户
5. 登录用户

#1. 获取JSON Web 密钥集 (JWKS)

端点：GET /.well-known/jwks.json
摘要：检索JSON Web 密钥集 (JWKS)。
产生：application/json

#请求

CURL：

curl -X GET "{{API_BASE_URL}}/api/v2/auth/.well-known/jwks.json" \
  -H "Accept: application/json"

#回应

• 200 好
  描述： JSON Web 密钥集
  类型：对象
  Schema：

  {
    keys: {
      alg: string;
      e: string;
      kid: string;
      kty: string;
      n: string;
      use: string;
    }[];
  }
  

  示例：

  {
    "keys": [
      {
        "alg": "RS256",
        "e": "AQAB",
        "kid": "key-id-123",
        "kty": "RSA",
        "n": "base64-encoded-key",
        "use": "sig"
      }
    ]
  }
  

• 有关错误状态（4xx、5xx），请参阅 API-错误处理

#2. 获取OpenID配置

端点：GET /.well-known/openid-configuration
摘要：检索OpenID配置。
产生：application/json

#请求

CURL：

curl -X GET "{{API_BASE_URL}}/api/v2/auth/.well-known/openid-configuration" \
  -H "Accept: application/json"

#回应

• 200 好
  描述：OpenID 配置
  类型：对象
  Schema：

  {
    issuer: string;
    jwks_uri: string;
    token_endpoint: string;
  }
  

  示例：

  {
    "issuer": "{{API_BASE_URL}}/api/v2/auth",
    "jwks_uri": "{{API_BASE_URL}}/api/v2/auth/.well-known/jwks.json",
    "token_endpoint": "{{API_BASE_URL}}/api/v2/auth/token"
  }
  

• 有关错误状态（4xx、5xx），请参阅 API-错误处理

#3.创建代理

端点：POST /a/agents
摘要：创建一个新代理。代理可以是管理员、操作员或用户。
权限：auth.agents.create
消耗：application/json
产生：application/json
安全：BearerAuth（授权：持有者abcde12345）

#请求

CURL：

curl -X POST "{{API_BASE_URL}}/api/v2/auth/a/agents" \
  -H "Authorization: Bearer abcde12345" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newagent",
    "password": "securepassword123"
  }'

参数：

• Body：创建代理请求（必填）
  类型：对象
  Schema：

  {
    username: string; // Required, minLength: 6, maxLength: 64
    password?: string; // Optional, minLength: 6, maxLength: 256
  }
  

  示例：

  {
    "username": "newagent",
    "password": "securepassword123"
  }
  

#回应

• 200 好
  描述：好的
  类型：对象
  Schema：

  {
    id: string;
    username: string;
  }
  

  示例：

  {
    "id": "user-uuid-123",
    "username": "newagent"
  }
  

• 有关错误状态（4xx、5xx），请参阅 API-错误处理

#4. 强制注销用户

端点：POST /a/users/{username}/force-logout
摘要：强制注销用户。
权限：auth.users.forceLogout
消耗：application/json
产生：文本/纯文本
安全：BearerAuth（授权：承载abcde12345）

#请求

CURL：

curl -X POST "{{API_BASE_URL}}/api/v2/auth/a/users/testuser/force-logout" \
  -H "Authorization: Bearer abcde12345" \
  -H "Content-Type: application/json"

参数：

• 路径：用户名（必填，类型：字符串）
  示例：测试用户

#回应

• 200 好
  描述：好的
  类型：字符串
  示例：

  User logged out successfully
  

• 有关错误状态（4xx、5xx），请参阅 API-错误处理

#5. 登录用户

端点：POST /login
摘要：对用户进行身份验证并返回令牌。
消耗：application/json
产生：application/json

#请求

CURL：

curl -X POST "{{API_BASE_URL}}/api/v2/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "password": "securepassword123"
  }'

参数：

• Body：登录请求（必填）
  类型：对象
  Schema：

  {
    username: string; // Required, minLength: 6, maxLength: 64
    password: string; // Required, minLength: 6, maxLength: 256
  }
  

  示例：

  {
    "username": "testuser",
    "password": "securepassword123"
  }
  

#回应

• 200 好
  描述：好的
  类型：对象
  Schema：

  {
    accessToken?: string;
    altId?: number;
    email?: string;
    id?: string;
    idToken?: string;
    refreshToken?: string;
    telegramId?: number;
    username?: string;
  }
  

  示例：

  {
    "accessToken": "jwt-token-123",
    "altId": 123,
    "email": "testuser@example.com",
    "id": "user-uuid-123",
    "idToken": "id-token-123",
    "refreshToken": "refresh-token-123",
    "telegramId": 456,
    "username": "testuser"
  }
  

• 有关错误状态（4xx、5xx），请参阅 API-错误处理