#身份驗證服務 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"
  }'

參數：

• 內文：建立代理請求（必填） 類型：對象 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"
  }'

參數：

• 內文：登入請求（必填） 類型：對象 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-錯誤處理