接入方服务端接入:账号与动态码
当前流程: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)
}
}