621 lines
22 KiB
Plaintext
621 lines
22 KiB
Plaintext
syntax = "v1"
|
||
|
||
type (
|
||
RegisterReq {
|
||
TenantSlug string `json:"tenant_slug" validate:"required"` // 租戶 slug（小寫英數）
|
||
InviteCode string `json:"invite_code" validate:"required"` // 邀請碼
|
||
Email string `json:"email" validate:"required,email"` // 電子郵件
|
||
Password string `json:"password" validate:"required,min=8,max=128"` // 密碼（8-128 字元）
|
||
DisplayName string `json:"display_name,optional"` // 顯示名稱（可選）
|
||
Language string `json:"language,optional"` // 語系代碼，如 zh-TW / en（可選）
|
||
AcceptTermsVersion string `json:"accept_terms_version" validate:"required"` // 使用者接受的服務條款版本
|
||
MarketingOptIn bool `json:"marketing_opt_in,optional"` // 是否同意接收行銷訊息
|
||
}
|
||
|
||
RegisterData {
|
||
ChallengeID string `json:"challenge_id"`
|
||
ExpiresIn int `json:"expires_in"`
|
||
UID string `json:"uid"`
|
||
}
|
||
|
||
RegisterConfirmReq {
|
||
TenantSlug string `json:"tenant_slug" validate:"required"` // 租戶 slug
|
||
ChallengeID string `json:"challenge_id" validate:"required"` // 註冊流程的 OTP challenge ID（由 /register 回傳）
|
||
Code string `json:"code" validate:"required,len=6"` // 6 位數 OTP 驗證碼
|
||
}
|
||
|
||
RegisterResendReq {
|
||
TenantSlug string `json:"tenant_slug" validate:"required"` // 租戶 slug
|
||
ChallengeID string `json:"challenge_id" validate:"required"` // 註冊流程的 OTP challenge ID
|
||
}
|
||
|
||
RegisterResumeReq {
|
||
TenantSlug string `json:"tenant_slug" validate:"required"` // 租戶 slug
|
||
Email string `json:"email" validate:"required,email"` // 註冊 Email
|
||
}
|
||
|
||
PasswordForgotReq {
|
||
TenantSlug string `json:"tenant_slug" validate:"required"` // 租戶 slug
|
||
Email string `json:"email" validate:"required,email"` // 登入 Email
|
||
}
|
||
|
||
PasswordForgotData {
|
||
ChallengeID string `json:"challenge_id"`
|
||
ExpiresIn int `json:"expires_in"`
|
||
}
|
||
|
||
PasswordResetReq {
|
||
TenantSlug string `json:"tenant_slug" validate:"required"` // 租戶 slug
|
||
ChallengeID string `json:"challenge_id" validate:"required"` // 忘記密碼 OTP challenge ID
|
||
Code string `json:"code" validate:"required,len=6"` // 6 位數 OTP
|
||
NewPassword string `json:"new_password" validate:"required,min=8,max=128"` // 新密碼
|
||
}
|
||
|
||
PasswordResetData {
|
||
OK bool `json:"ok"`
|
||
}
|
||
|
||
AuthTokenData {
|
||
AccessToken string `json:"access_token"`
|
||
RefreshToken string `json:"refresh_token"`
|
||
ExpiresIn int64 `json:"expires_in"`
|
||
UID string `json:"uid"`
|
||
TokenType string `json:"token_type"`
|
||
}
|
||
|
||
RegisterSocialStartReq {
|
||
TenantSlug string `json:"tenant_slug" validate:"required"` // 租戶 slug
|
||
InviteCode string `json:"invite_code" validate:"required"` // 邀請碼
|
||
Provider string `json:"provider,options=google|ldap" validate:"required,oneof=google ldap"` // 第三方登入提供者；可選值: google / ldap
|
||
AcceptTermsVersion string `json:"accept_terms_version" validate:"required"` // 使用者接受的服務條款版本
|
||
Language string `json:"language,optional"` // 語系代碼，如 zh-TW / en（可選）
|
||
RedirectURI string `json:"redirect_uri" validate:"required,url"` // OAuth 完成後要 redirect 回的 URI
|
||
MarketingOptIn bool `json:"marketing_opt_in,optional"` // 是否同意接收行銷訊息
|
||
}
|
||
|
||
RegisterSocialStartData {
|
||
OauthURL string `json:"oauth_url"`
|
||
SessionID string `json:"session_id"`
|
||
ExpiresIn int `json:"expires_in"`
|
||
}
|
||
|
||
RegisterSocialCallbackReq {
|
||
Code string `form:"code" validate:"required"` // IdP 回傳的 OAuth authorization code
|
||
State string `form:"state" validate:"required"` // IdP 回傳的 OAuth state（對應 session）
|
||
}
|
||
|
||
LoginReq {
|
||
TenantSlug string `json:"tenant_slug" validate:"required"` // 租戶 slug
|
||
Email string `json:"email" validate:"required,email"` // 電子郵件
|
||
Password string `json:"password" validate:"required,min=8,max=128"` // 密碼（8-128 字元）
|
||
}
|
||
|
||
LoginData {
|
||
AccessToken string `json:"access_token,optional"`
|
||
RefreshToken string `json:"refresh_token,optional"`
|
||
ExpiresIn int64 `json:"expires_in,optional"`
|
||
UID string `json:"uid,optional"`
|
||
TokenType string `json:"token_type,optional"`
|
||
MFARequired bool `json:"mfa_required,optional"`
|
||
MFAChallengeID string `json:"mfa_challenge_id,optional"`
|
||
MFAExpiresIn int `json:"mfa_expires_in,optional"`
|
||
}
|
||
|
||
LoginMFAConfirmReq {
|
||
TenantSlug string `json:"tenant_slug" validate:"required"` // 租戶 slug
|
||
ChallengeID string `json:"challenge_id" validate:"required"` // 密碼登入後回傳的 MFA challenge ID
|
||
Code string `json:"code" validate:"required,min=6,max=32"` // TOTP 6 碼或備援碼
|
||
}
|
||
|
||
TokenRefreshReq {
|
||
RefreshToken string `json:"refresh_token" validate:"required"` // 先前核發的 refresh token
|
||
}
|
||
|
||
TokenExchangeReq {
|
||
TenantSlug string `json:"tenant_slug" validate:"required"` // 租戶 slug
|
||
IDToken string `json:"id_token" validate:"required"` // ZITADEL 發行的 id_token
|
||
}
|
||
|
||
LoginSocialStartReq {
|
||
TenantSlug string `json:"tenant_slug" validate:"required"` // 租戶 slug
|
||
Provider string `json:"provider,options=google|ldap" validate:"required,oneof=google ldap"` // 第三方登入提供者；可選值: google / ldap
|
||
RedirectURI string `json:"redirect_uri" validate:"required,url"` // OAuth 完成後要 redirect 回的 URI
|
||
}
|
||
|
||
LoginSocialStartData {
|
||
OauthURL string `json:"oauth_url"`
|
||
SessionID string `json:"session_id"`
|
||
ExpiresIn int `json:"expires_in"`
|
||
}
|
||
|
||
LoginSocialCallbackReq {
|
||
Code string `form:"code" validate:"required"` // IdP 回傳的 OAuth authorization code
|
||
State string `form:"state" validate:"required"` // IdP 回傳的 OAuth state（對應 session）
|
||
}
|
||
|
||
LogoutData {
|
||
OK bool `json:"ok"`
|
||
}
|
||
|
||
// 文件用：成功回應 envelope（HTTP 200, code=102000, message=SUCCESS）
|
||
RegisterOKStatus {
|
||
Code int64 `json:"code"`
|
||
Message string `json:"message"`
|
||
Data RegisterData `json:"data"`
|
||
}
|
||
|
||
AuthTokenOKStatus {
|
||
Code int64 `json:"code"`
|
||
Message string `json:"message"`
|
||
Data AuthTokenData `json:"data"`
|
||
}
|
||
|
||
LoginOKStatus {
|
||
Code int64 `json:"code"`
|
||
Message string `json:"message"`
|
||
Data LoginData `json:"data"`
|
||
}
|
||
|
||
RegisterSocialStartOKStatus {
|
||
Code int64 `json:"code"`
|
||
Message string `json:"message"`
|
||
Data RegisterSocialStartData `json:"data"`
|
||
}
|
||
|
||
LoginSocialStartOKStatus {
|
||
Code int64 `json:"code"`
|
||
Message string `json:"message"`
|
||
Data LoginSocialStartData `json:"data"`
|
||
}
|
||
|
||
LogoutOKStatus {
|
||
Code int64 `json:"code"`
|
||
Message string `json:"message"`
|
||
Data LogoutData `json:"data"`
|
||
}
|
||
|
||
PasswordForgotOKStatus {
|
||
Code int64 `json:"code"`
|
||
Message string `json:"message"`
|
||
Data PasswordForgotData `json:"data"`
|
||
}
|
||
|
||
PasswordResetOKStatus {
|
||
Code int64 `json:"code"`
|
||
Message string `json:"message"`
|
||
Data PasswordResetData `json:"data"`
|
||
}
|
||
)
|
||
|
||
@server(
|
||
group: auth
|
||
prefix: /api/v1/auth
|
||
tags: "Auth - 認證（公開）"
|
||
summary: "註冊 / 登入 / Token 交換（不需 Bearer）"
|
||
)
|
||
service gateway {
|
||
@doc "Email 註冊（建立 ZITADEL + member，寄 registration OTP）"
|
||
/*
|
||
@respdoc-200 (RegisterOKStatus) // 成功（code=102000）
|
||
@respdoc-400 (
|
||
10101000: (APIErrorStatus) 參數格式錯誤
|
||
10104000: (APIErrorStatus) 缺少必填欄位
|
||
) // 參數錯誤 / 驗證失敗
|
||
@respdoc-403 (
|
||
28505000: (APIErrorStatus) tenant 不允許註冊
|
||
) // 禁止存取
|
||
@respdoc-404 (
|
||
29301000: (APIErrorStatus) tenant 不存在（Member scope）
|
||
) // 資源不存在
|
||
@respdoc-409 (
|
||
28303000: (APIErrorStatus) email 已註冊（Auth scope）
|
||
) // 資源衝突
|
||
@respdoc-423 (
|
||
28313000: (APIErrorStatus) invite 消耗鎖定中
|
||
) // 資源鎖定
|
||
@respdoc-429 (
|
||
28604000: (APIErrorStatus) OTP 重送冷卻
|
||
28310000: (APIErrorStatus) invite 次數用盡
|
||
) // 請求過於頻繁
|
||
@respdoc-500 (
|
||
28201000: (APIErrorStatus) 資料庫錯誤
|
||
28601000: (APIErrorStatus) 系統內部錯誤
|
||
) // 內部錯誤
|
||
@respdoc-501 (
|
||
28605000: (APIErrorStatus) 功能未配置
|
||
) // 未實作
|
||
@respdoc-502 (
|
||
28802000: (APIErrorStatus) ZITADEL 第三方錯誤
|
||
) // 第三方服務錯誤
|
||
*/
|
||
@handler register
|
||
post /register (RegisterReq) returns (RegisterData)
|
||
|
||
@doc "確認 registration OTP 並核發 JWT"
|
||
/*
|
||
@respdoc-200 (AuthTokenOKStatus) // 成功（code=102000）
|
||
@respdoc-400 (
|
||
10101000: (APIErrorStatus) 參數格式錯誤
|
||
10104000: (APIErrorStatus) 缺少必填欄位
|
||
) // 參數錯誤 / 驗證失敗
|
||
@respdoc-403 (
|
||
28505000: (APIErrorStatus) challenge tenant 或 purpose 不符（Auth scope）
|
||
29505000: (APIErrorStatus) OTP 無效（Member scope）
|
||
) // 禁止存取
|
||
@respdoc-404 (
|
||
29301000: (APIErrorStatus) tenant / OTP challenge 不存在（Member scope）
|
||
) // 資源不存在
|
||
@respdoc-409 (
|
||
28309000: (APIErrorStatus) registration challenge 狀態無效（Auth scope）
|
||
29309000: (APIErrorStatus) OTP challenge 鎖定（Member scope）
|
||
) // 資源狀態衝突
|
||
@respdoc-500 (
|
||
28201000: (APIErrorStatus) 資料庫錯誤
|
||
28601000: (APIErrorStatus) 系統內部錯誤
|
||
) // 內部錯誤
|
||
@respdoc-501 (
|
||
28605000: (APIErrorStatus) 功能未配置
|
||
) // 未實作
|
||
*/
|
||
@handler registerConfirm
|
||
post /register/confirm (RegisterConfirmReq) returns (AuthTokenData)
|
||
|
||
@doc "重寄 registration OTP"
|
||
/*
|
||
@respdoc-200 (RegisterOKStatus) // 成功（code=102000）
|
||
@respdoc-400 (
|
||
10101000: (APIErrorStatus) 參數格式錯誤
|
||
10104000: (APIErrorStatus) 缺少必填欄位
|
||
) // 參數錯誤
|
||
@respdoc-403 (
|
||
28505000: (APIErrorStatus) challenge tenant 或 purpose 不符
|
||
) // 禁止存取
|
||
@respdoc-404 (
|
||
29301000: (APIErrorStatus) tenant / OTP challenge 不存在（Member scope）
|
||
) // 資源不存在
|
||
@respdoc-409 (
|
||
28309000: (APIErrorStatus) registration challenge 不完整（Auth scope）
|
||
) // 資源狀態衝突
|
||
@respdoc-429 (
|
||
28604000: (APIErrorStatus) OTP 重送冷卻
|
||
) // 請求過於頻繁
|
||
@respdoc-500 (
|
||
28201000: (APIErrorStatus) 資料庫錯誤
|
||
28601000: (APIErrorStatus) 系統內部錯誤
|
||
) // 內部錯誤
|
||
@respdoc-501 (
|
||
28605000: (APIErrorStatus) 功能未配置
|
||
) // 未實作
|
||
*/
|
||
@handler registerResend
|
||
post /register/resend (RegisterResendReq) returns (RegisterData)
|
||
|
||
@doc "恢復未完成註冊（依 Email 重寄 registration OTP）"
|
||
/*
|
||
@respdoc-200 (RegisterOKStatus) // 成功（code=102000）
|
||
@respdoc-400 (
|
||
10101000: (APIErrorStatus) 參數格式錯誤
|
||
10104000: (APIErrorStatus) 缺少必填欄位
|
||
) // 參數錯誤
|
||
@respdoc-404 (
|
||
29301000: (APIErrorStatus) tenant / 待驗證 member 不存在（Member scope）
|
||
) // 資源不存在
|
||
@respdoc-409 (
|
||
28309000: (APIErrorStatus) 帳號已完成驗證（Auth scope）
|
||
) // 資源狀態衝突
|
||
@respdoc-429 (
|
||
28604000: (APIErrorStatus) OTP 重送冷卻
|
||
) // 請求過於頻繁
|
||
@respdoc-500 (
|
||
28201000: (APIErrorStatus) 資料庫錯誤
|
||
28601000: (APIErrorStatus) 系統內部錯誤
|
||
) // 內部錯誤
|
||
@respdoc-501 (
|
||
28605000: (APIErrorStatus) 功能未配置
|
||
) // 未實作
|
||
*/
|
||
@handler registerResume
|
||
post /register/resume (RegisterResumeReq) returns (RegisterData)
|
||
|
||
@doc "忘記密碼：寄送重設 OTP（僅 platform_native 平台帳號）"
|
||
/*
|
||
@respdoc-200 (PasswordForgotOKStatus) // 成功（code=102000）
|
||
@respdoc-400 (
|
||
10101000: (APIErrorStatus) 參數格式錯誤
|
||
10104000: (APIErrorStatus) 缺少必填欄位
|
||
) // 參數錯誤
|
||
@respdoc-403 (
|
||
28505000: (APIErrorStatus) 外部身份帳號不可重設密碼（Auth scope）
|
||
) // 禁止存取
|
||
@respdoc-404 (
|
||
29301000: (APIErrorStatus) tenant / member 不存在（Member scope）
|
||
) // 資源不存在
|
||
@respdoc-429 (
|
||
29604000: (APIErrorStatus) OTP 重送冷卻
|
||
) // 請求過於頻繁
|
||
@respdoc-501 (
|
||
28605000: (APIErrorStatus) 功能未配置
|
||
) // 未實作
|
||
*/
|
||
@handler passwordForgot
|
||
post /password/forgot (PasswordForgotReq) returns (PasswordForgotData)
|
||
|
||
@doc "忘記密碼：驗證 OTP 並重設密碼（僅 platform_native）"
|
||
/*
|
||
@respdoc-200 (PasswordResetOKStatus) // 成功（code=102000）
|
||
@respdoc-400 (
|
||
10101000: (APIErrorStatus) 參數格式錯誤
|
||
10104000: (APIErrorStatus) 缺少必填欄位
|
||
) // 參數錯誤
|
||
@respdoc-403 (
|
||
28505000: (APIErrorStatus) OTP 無效（Auth scope）
|
||
29505000: (APIErrorStatus) OTP 無效（Member scope）
|
||
) // 禁止存取
|
||
@respdoc-404 (
|
||
29301000: (APIErrorStatus) tenant / OTP challenge 不存在（Member scope）
|
||
) // 資源不存在
|
||
@respdoc-502 (
|
||
28802000: (APIErrorStatus) ZITADEL 第三方錯誤
|
||
) // 第三方服務錯誤
|
||
*/
|
||
@handler passwordReset
|
||
post /password/reset (PasswordResetReq) returns (PasswordResetData)
|
||
|
||
@doc "Social 註冊：建立 session 並回傳 OAuth URL"
|
||
/*
|
||
@respdoc-200 (RegisterSocialStartOKStatus) // 成功（code=102000）
|
||
@respdoc-400 (
|
||
10101000: (APIErrorStatus) 參數格式錯誤
|
||
10104000: (APIErrorStatus) 缺少必填欄位
|
||
28101000: (APIErrorStatus) invite 已過期（Auth scope）
|
||
) // 參數錯誤
|
||
@respdoc-403 (
|
||
28505000: (APIErrorStatus) tenant 不允許註冊
|
||
) // 禁止存取
|
||
@respdoc-404 (
|
||
29301000: (APIErrorStatus) tenant 不存在（Member scope）
|
||
28301000: (APIErrorStatus) invite 不存在（Auth scope）
|
||
) // 資源不存在
|
||
@respdoc-429 (
|
||
28310000: (APIErrorStatus) invite 次數用盡
|
||
) // 配額不足
|
||
@respdoc-500 (
|
||
28201000: (APIErrorStatus) 資料庫錯誤
|
||
28601000: (APIErrorStatus) 系統內部錯誤
|
||
) // 內部錯誤
|
||
@respdoc-501 (
|
||
28605000: (APIErrorStatus) 功能未配置
|
||
) // 未實作
|
||
@respdoc-502 (
|
||
28802000: (APIErrorStatus) ZITADEL 第三方錯誤
|
||
) // 第三方服務錯誤
|
||
*/
|
||
@handler registerSocialStart
|
||
post /register/social/start (RegisterSocialStartReq) returns (RegisterSocialStartData)
|
||
|
||
@doc "Social 註冊 OAuth callback"
|
||
/*
|
||
@respdoc-200 (AuthTokenOKStatus) // 成功（code=102000）
|
||
@respdoc-400 (
|
||
10101000: (APIErrorStatus) 參數格式錯誤
|
||
10104000: (APIErrorStatus) 缺少必填欄位
|
||
28101000: (APIErrorStatus) oauth state 無效（Auth scope）
|
||
) // 參數錯誤
|
||
@respdoc-403 (
|
||
28505000: (APIErrorStatus) social email 未驗證
|
||
) // 禁止存取
|
||
@respdoc-404 (
|
||
28301000: (APIErrorStatus) registration session 不存在（Auth scope）
|
||
29301000: (APIErrorStatus) tenant 不存在（Member scope）
|
||
) // 資源不存在
|
||
@respdoc-409 (
|
||
28303000: (APIErrorStatus) 帳號已存在（引導 login）
|
||
) // 資源衝突
|
||
@respdoc-423 (
|
||
28313000: (APIErrorStatus) invite 消耗鎖定中
|
||
) // 資源鎖定
|
||
@respdoc-429 (
|
||
28310000: (APIErrorStatus) invite 次數用盡
|
||
) // 配額不足
|
||
@respdoc-500 (
|
||
28201000: (APIErrorStatus) 資料庫錯誤
|
||
28601000: (APIErrorStatus) 系統內部錯誤
|
||
) // 內部錯誤
|
||
@respdoc-501 (
|
||
28605000: (APIErrorStatus) 功能未配置
|
||
) // 未實作
|
||
@respdoc-502 (
|
||
28802000: (APIErrorStatus) ZITADEL 第三方錯誤
|
||
) // 第三方服務錯誤
|
||
*/
|
||
@handler registerSocialCallback
|
||
get /register/social/callback (RegisterSocialCallbackReq) returns (AuthTokenData)
|
||
|
||
@doc "Email + 密碼登入（ZITADEL ROPG → CloudEP JWT；若已啟用 TOTP 則回傳 MFA challenge）"
|
||
/*
|
||
@respdoc-200 (LoginOKStatus) // 成功（code=102000）；mfa_required=true 時僅含 challenge
|
||
@respdoc-400 (
|
||
10101000: (APIErrorStatus) 參數格式錯誤
|
||
10104000: (APIErrorStatus) 缺少必填欄位
|
||
) // 參數錯誤
|
||
@respdoc-401 (
|
||
28501000: (APIErrorStatus) 帳密錯誤
|
||
) // 未授權
|
||
@respdoc-403 (
|
||
28505000: (APIErrorStatus) 帳號未驗證 / 停權 / 不允許登入
|
||
) // 禁止存取
|
||
@respdoc-404 (
|
||
29301000: (APIErrorStatus) tenant 不存在（Member scope）
|
||
) // 資源不存在
|
||
@respdoc-500 (
|
||
28201000: (APIErrorStatus) 資料庫錯誤
|
||
28601000: (APIErrorStatus) 系統內部錯誤
|
||
) // 內部錯誤
|
||
@respdoc-501 (
|
||
28605000: (APIErrorStatus) 功能未配置
|
||
) // 未實作
|
||
@respdoc-502 (
|
||
28802000: (APIErrorStatus) ZITADEL 第三方錯誤
|
||
) // 第三方服務錯誤
|
||
*/
|
||
@handler login
|
||
post /login (LoginReq) returns (LoginData)
|
||
|
||
@doc "確認登入 MFA（TOTP / 備援碼）並核發 JWT"
|
||
/*
|
||
@respdoc-200 (AuthTokenOKStatus) // 成功（code=102000）
|
||
@respdoc-400 (
|
||
10101000: (APIErrorStatus) 參數格式錯誤
|
||
10104000: (APIErrorStatus) 缺少必填欄位
|
||
) // 參數錯誤
|
||
@respdoc-403 (
|
||
28505000: (APIErrorStatus) TOTP 無效 / challenge tenant 不符（Auth scope）
|
||
29505000: (APIErrorStatus) OTP 無效（Member scope）
|
||
) // 禁止存取
|
||
@respdoc-404 (
|
||
29301000: (APIErrorStatus) tenant 不存在（Member scope）
|
||
28301000: (APIErrorStatus) login mfa challenge 不存在（Auth scope）
|
||
) // 資源不存在
|
||
@respdoc-500 (
|
||
28201000: (APIErrorStatus) 資料庫錯誤
|
||
28601000: (APIErrorStatus) 系統內部錯誤
|
||
) // 內部錯誤
|
||
@respdoc-501 (
|
||
28605000: (APIErrorStatus) 功能未配置
|
||
) // 未實作
|
||
*/
|
||
@handler loginMfaConfirm
|
||
post /login/mfa (LoginMFAConfirmReq) returns (AuthTokenData)
|
||
|
||
@doc "以 refresh_token 換發新的 access/refresh token"
|
||
/*
|
||
@respdoc-200 (AuthTokenOKStatus) // 成功（code=102000）
|
||
@respdoc-400 (
|
||
10101000: (APIErrorStatus) 參數格式錯誤
|
||
10104000: (APIErrorStatus) 缺少 refresh_token
|
||
) // 參數錯誤
|
||
@respdoc-401 (
|
||
28501000: (APIErrorStatus) refresh token 無效或已撤銷
|
||
) // 未授權
|
||
@respdoc-500 (
|
||
28601000: (APIErrorStatus) 系統內部錯誤
|
||
) // 內部錯誤
|
||
@respdoc-501 (
|
||
28605000: (APIErrorStatus) 功能未配置
|
||
) // 未實作
|
||
*/
|
||
@handler tokenRefresh
|
||
post /token/refresh (TokenRefreshReq) returns (AuthTokenData)
|
||
|
||
@doc "ZITADEL id_token 換 CloudEP JWT（企業 SSO）"
|
||
/*
|
||
@respdoc-200 (AuthTokenOKStatus) // 成功（code=102000）
|
||
@respdoc-400 (
|
||
10101000: (APIErrorStatus) 參數格式錯誤
|
||
10104000: (APIErrorStatus) 缺少必填欄位
|
||
) // 參數錯誤
|
||
@respdoc-401 (
|
||
28501000: (APIErrorStatus) id_token 無效
|
||
) // 未授權
|
||
@respdoc-403 (
|
||
28505000: (APIErrorStatus) 帳號未驗證 / 停權 / 不允許登入
|
||
) // 禁止存取
|
||
@respdoc-404 (
|
||
29301000: (APIErrorStatus) tenant / member 不存在（Member scope）
|
||
) // 資源不存在
|
||
@respdoc-500 (
|
||
28201000: (APIErrorStatus) 資料庫錯誤
|
||
28601000: (APIErrorStatus) 系統內部錯誤
|
||
) // 內部錯誤
|
||
@respdoc-501 (
|
||
28605000: (APIErrorStatus) 功能未配置
|
||
) // 未實作
|
||
@respdoc-502 (
|
||
28802000: (APIErrorStatus) ZITADEL 第三方錯誤
|
||
) // 第三方服務錯誤
|
||
*/
|
||
@handler tokenExchange
|
||
post /token/exchange (TokenExchangeReq) returns (AuthTokenData)
|
||
|
||
@doc "Social 登入：建立 login session 並回傳 OAuth URL（不含 invite）"
|
||
/*
|
||
@respdoc-200 (LoginSocialStartOKStatus) // 成功（code=102000）
|
||
@respdoc-400 (
|
||
10101000: (APIErrorStatus) 參數格式錯誤
|
||
10104000: (APIErrorStatus) 缺少必填欄位
|
||
) // 參數錯誤
|
||
@respdoc-403 (
|
||
28505000: (APIErrorStatus) tenant 不允許登入
|
||
) // 禁止存取
|
||
@respdoc-404 (
|
||
29301000: (APIErrorStatus) tenant 不存在（Member scope）
|
||
) // 資源不存在
|
||
@respdoc-500 (
|
||
28201000: (APIErrorStatus) 資料庫錯誤
|
||
28601000: (APIErrorStatus) 系統內部錯誤
|
||
) // 內部錯誤
|
||
@respdoc-501 (
|
||
28605000: (APIErrorStatus) 功能未配置
|
||
) // 未實作
|
||
@respdoc-502 (
|
||
28802000: (APIErrorStatus) ZITADEL 第三方錯誤
|
||
) // 第三方服務錯誤
|
||
*/
|
||
@handler loginSocialStart
|
||
post /login/social/start (LoginSocialStartReq) returns (LoginSocialStartData)
|
||
|
||
@doc "Social 登入 OAuth callback"
|
||
/*
|
||
@respdoc-200 (LoginOKStatus) // 成功（code=102000）；若已啟用 TOTP 則僅回 MFA challenge
|
||
@respdoc-400 (
|
||
10101000: (APIErrorStatus) 參數格式錯誤
|
||
10104000: (APIErrorStatus) 缺少必填欄位
|
||
28101000: (APIErrorStatus) oauth state 無效（Auth scope）
|
||
) // 參數錯誤
|
||
@respdoc-403 (
|
||
28505000: (APIErrorStatus) social email 未驗證 / 帳號狀態不允許登入
|
||
) // 禁止存取
|
||
@respdoc-404 (
|
||
28301000: (APIErrorStatus) login session 不存在（Auth scope）
|
||
29301000: (APIErrorStatus) tenant / member 不存在（Member scope）
|
||
) // 資源不存在
|
||
@respdoc-500 (
|
||
28201000: (APIErrorStatus) 資料庫錯誤
|
||
28601000: (APIErrorStatus) 系統內部錯誤
|
||
) // 內部錯誤
|
||
@respdoc-501 (
|
||
28605000: (APIErrorStatus) 功能未配置
|
||
) // 未實作
|
||
@respdoc-502 (
|
||
28802000: (APIErrorStatus) ZITADEL 第三方錯誤
|
||
) // 第三方服務錯誤
|
||
*/
|
||
@handler loginSocialCallback
|
||
get /login/social/callback (LoginSocialCallbackReq) returns (LoginData)
|
||
}
|
||
|
||
@server(
|
||
group: auth
|
||
prefix: /api/v1/auth
|
||
middleware: AuthJWT
|
||
tags: "Auth - 認證（需 Bearer）"
|
||
summary: "登出（需 access token）"
|
||
)
|
||
service gateway {
|
||
@doc "登出（撤銷 access JWT 及配對 refresh JWT）"
|
||
/*
|
||
@respdoc-200 (LogoutOKStatus) // 成功（code=102000）
|
||
@respdoc-401 (
|
||
28501000: (APIErrorStatus) 缺少或無效 access token
|
||
) // 未授權
|
||
@respdoc-500 (
|
||
28601000: (APIErrorStatus) 系統內部錯誤
|
||
) // 內部錯誤
|
||
@respdoc-501 (
|
||
28605000: (APIErrorStatus) 功能未配置
|
||
) // 未實作
|
||
*/
|
||
@handler logout
|
||
post /logout returns (LogoutData)
|
||
}
|