接入方服務端接入:帳號與動態碼
目前流程:App 直接顯示六位動態碼
首次綁定時,使用者掃描網站二維碼,在 App 完成裝置驗證,再把 App 目前動態碼輸入網站。網站驗證成功後完成綁定。後續登入和敏感操作,使用者在網站輸入帳號目前動態碼完成驗證。
帳號密碼通過後,接入方服務端 儲存待驗證工作階段;動態碼驗證成功後,授予正式登入權限。每個敏感操作分別驗證。
接入方服務端儲存待驗證表單,檢查使用者權限,並在動態碼驗證成功後,將回執與對應業務操作在同一交易中提交。
接入方需要的三個核心介面
建立首次綁定、查詢帳號狀態、驗證動態碼分別使用以下三個介面。
externalUserId 是同一接入方內唯一、穩定的 接入方使用者識別碼,長度為 1–128 個可見 ASCII 字元。使用 cid-username 時,應保證組合唯一且長期固定。accountLabel 用於顯示名稱。
接入方憑據只在伺服器端保存
API Origin 使用部署時提供的 AUTHLINK_ORIGIN。所有整合介面使用 Authorization: Bearer 接入方密鑰。動態碼驗證及首次綁定建立還需要穩定的 Idempotency-Key;同一操作重試必須重用原鍵。
帳號綁定狀態
POST /v1/integration/accounts/status
{"externalUserId":"user-100"}接入方服務端從工作階段取得 externalUserId。unbound 表示未綁定,bound 表示已綁定,deleted 表示已永久撤銷。
成功回傳 HTTP 200。platform 在 unbound、deleted 時為 null,在 bound 時為 android 或 ios。接入方服務端 同時檢查自己管理的使用者啟用狀態。
首次掃碼綁定
POST /v1/integration/requests
{"externalUserId":"user-100","accountLabel":"Demo account","purpose":"bind","state":"<43-character random token>"}後台分別隨機產生 state 和建立冪等鍵,把 qr 與 expiresAt 回傳目前工作階段展示。使用者掃碼完成裝置驗證後,在接入方客戶端輸入 App 目前動態碼,後台呼叫 auth 完成綁定。
建立綁定成功回傳 HTTP 200,包含 requestId、qr、qrSvg、purpose 和 expiresAt;首次掃碼憑據自建立起有效 60 分鐘;掃碼、取碼和重試不延長期限,六位動態碼仍最多有效一分鐘。accountLabel 必填,最多 160 個 UTF-8 位元組,不允許控制字元;purpose 固定為 bind。state 與 Idempotency-Key 必須分別產生,均為 32 位元組安全隨機數的無填充 Base64URL(43 字元)。
同一 externalUserId 已綁定時,新建綁定回傳 HTTP 409 / ACCOUNT_ALREADY_BOUND;已撤銷回傳 HTTP 409 / ACCOUNT_UNAVAILABLE。原建立鍵與原參數重試,在憑據未過期時可能回傳原二維碼;參數改變卻重用鍵回傳 IDEMPOTENCY_CONFLICT,原憑據過期回傳 REQUEST_EXPIRED(均為 HTTP 409)。
選用:按綁定 requestId 查詢進度
GET /v1/integration/requests/{requestId}
Authorization: Bearer <integrator API key>回傳 requestId、status、expiresAt。pending 表示等待手機驗證,approved 表示等待網站輸入動態碼,consumed 表示驗證完成,rejected 表示已拒絕,expired 表示已過期。最終帳號綁定狀態以 AccountStatus 為準。
直接驗證動態碼
POST /v1/integration/auth
Idempotency-Key: <saved key for this integrator server action>
{"externalUserId":"user-100","passcode":"001234"}passcode 使用六位 ASCII 數字字串,保留前導零。後台從目前工作階段取得 externalUserId,儲存業務表單與待辦關聯。
{
"status":"confirmed",
"verificationId":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
"authenticationPolicy":"device-signed-code.v1",
"tenantId":"BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
"externalUserId":"user-100",
"platform":"ios",
"verifiedAt":"2026-11-13T04:00:00Z",
"expiresAt":"2026-11-13T04:01:00Z"
}後台 SDK 會校驗使用者、接入方、策略、回執 ID 及期限。網站還須以 verificationId 唯一約束寫入資料,並與原表單操作於同一交易內提交;前端回呼只更新介面。
失敗、重試與一次性使用
App 在目前帳號頁連網驗證原裝置簽章後取得六位一次性碼,最多有效一分鐘;到期自動取新碼,斷網提示重試。新碼使舊碼失效,使用過的碼不能授權另一操作。
每個帳號在五分鐘計數窗口內累計五次錯誤或重複碼嘗試後,後續驗證回傳 PASSCODE_LOCKED。窗口結束後重新計數。接入方或請求頻率超限時回傳 RATE_LIMITED / HTTP 429。
PASSCODE_INVALID 401
PASSCODE_EXPIRED 401
PASSCODE_USED 409
PASSCODE_LOCKED 429
ACCOUNT_NOT_BOUND 409
ACCOUNT_UNAVAILABLE 409
APPROVAL_REQUIRED 409
KEY_MISMATCH 401
IDEMPOTENCY_CONFLICT 409
REQUEST_EXPIRED 409
INVALID_REQUEST 400
RATE_LIMITED 429PASSCODE_INVALID 表示碼錯誤;PASSCODE_EXPIRED 表示碼過期或已被取代;PASSCODE_USED 表示已使用;PASSCODE_LOCKED 表示嘗試次數受限。ACCOUNT_NOT_BOUND 表示未綁定;ACCOUNT_UNAVAILABLE 表示帳號已撤銷;APPROVAL_REQUIRED 表示首次裝置驗證尚未完成;KEY_MISMATCH 表示裝置綁定不符。
相同操作、相同冪等鍵和相同碼回傳同一回執。回執有效一分鐘,期限以 expiresAt 為準。接入方服務端 將輸碼錯誤顯示為驗證失敗,將網路或回應異常作為服務故障處理。
以上為 AuthLink API 的 HTTP 狀態和錯誤碼,錯誤體格式為 {"code":"錯誤碼"}。錯誤碼及其含義見上表。
接入方服務端 校驗並唯一儲存 verificationId,在回執有效期內與原待辦一併提交。同一待辦使用固定冪等鍵。收到明確驗證失敗後可換碼重試;網路結果不明時,使用原碼、原鍵重試。
永久撤銷綁定
POST /v1/integration/accounts/delete
{"externalUserId":"user-100"}成功回傳 status: deleted,永久撤銷該使用者的 AuthLink 綁定。接入方使用者由接入方自行管理。
Go SDK:驗證動態碼
client, err := authlink.New(authlink.Config{
Origin: os.Getenv("AUTHLINK_ORIGIN"),
TenantID: os.Getenv("AUTHLINK_TENANT_ID"),
APIKey: os.Getenv("AUTHLINK_API_KEY"),
})
if err != nil { return err }
// userID and authKey come from the integrator server session.
result, err := client.Authenticate(ctx, userID, passcode, authKey)
if err != nil { return err }
// Persist result.VerificationID and commit the saved operation once.Node SDK:驗證動態碼
const client = new AuthLink({ origin: process.env.AUTHLINK_ORIGIN,
tenantId: process.env.AUTHLINK_TENANT_ID, apiKey: process.env.AUTHLINK_API_KEY });
// Restore the user and stable authKey from the pending integrator server session.
const result = await client.authenticate(userId, passcode, authKey);
// Persist result.verificationId and execute the saved operation once.Go SDK
mkdir -p third_party
tar -xzf authlink-go.tar.gz -C third_party
go mod edit -replace=authlink.local/sdk=./third_party/authlink-go
go mod edit -require=authlink.local/[email protected]
go mod tidy// This example creates an enrollment ticket or verifies a device-signed code.
// Supply tenant credentials only through your backend's private environment.
package main
import (
"context"
"encoding/json"
"errors"
"flag"
"fmt"
"os"
"time"
authlink "authlink.local/sdk"
)
func run() error {
mode := flag.String("mode", "auth", "auth or create (first enrollment)")
user := flag.String("user", "", "stable user ID from your authenticated session")
label := flag.String("label", "", "account display label")
flag.Parse()
client, err := authlink.New(authlink.Config{Origin: os.Getenv("AUTHLINK_ORIGIN"), TenantID: os.Getenv("AUTHLINK_TENANT_ID"), APIKey: os.Getenv("AUTHLINK_API_KEY")})
if err != nil {
return err
}
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
switch *mode {
case "auth":
result, err := client.Authenticate(ctx, *user, os.Getenv("AUTHLINK_PASSCODE"), os.Getenv("AUTHLINK_AUTH_KEY"))
if err != nil {
return err
}
// Persist verificationId exactly once with the integrator server session's frozen action.
_ = result
fmt.Fprintln(os.Stderr, "Passcode verified; persist the receipt with the pending integrator server action before granting access.")
return nil
case "create":
// For this standalone example, supply already-generated and saved values
// through the environment. A website must persist them before networking.
ticket, err := client.CreateRequest(ctx, authlink.CreateInput{ExternalUserID: *user, AccountLabel: *label, Purpose: "bind", State: os.Getenv("AUTHLINK_STATE")}, os.Getenv("AUTHLINK_CREATE_KEY"))
if err != nil {
return err
}
// Contains QR token: deliver to the intended user's UI; never log it.
return json.NewEncoder(os.Stdout).Encode(ticket)
default:
return errors.New("mode must be auth or create")
}
}
func main() {
if err := run(); err != nil {
fmt.Fprintln(os.Stderr, err)
os.Exit(1)
}
}