服务端接入

接入流程与信任边界

1. 运营方为网站创建独立租户，把凭据交付网站后台。
2. 后台从已登录 session 取得稳定用户 ID，生成随机 state、创建幂等键和独立消费幂等键。
3. 创建 bind / confirm 请求，保存用户、会话、用途、state、requestId、expiresAt 及幂等键，再把公开 ticket 返回浏览器。
4. 用户在 AuthLink App 中核对网站、账号和数字，然后批准请求。
5. 后台查询到 approved / consumed 后，使用保存的 state 和消费幂等键调用 consume。
6. 校验回执，在自己的数据库事务中以 requestId / verificationId 唯一约束记录确认，才向网页返回 confirmed。受保护业务检查该记录。

没有 webhook。approved、六位数字以及前端回调都不能直接放行业务。AuthLink 不接收 action、金额、transactionHash 或业务授权范围。

租户与鉴权

向运营方获取本站的 tenantId、apiKey、origin 和 expiresAt。新密钥永久有效；运营方仍可轮换、撤销密钥或停用租户。旧密钥保留原有效期，只在网站后台安全保存。

创建请求与参数

POST /v1/integration/requests · API origin：

复制
{
  "externalUserId": "stable-user-id",
  "accountLabel": "Account display name",
  "purpose": "bind",
  "state": "REPLACE_WITH_SAVED_43_CHARACTER_RANDOM_STATE"
}

成功返回 HTTP 200 和 ticket：

同一账号的新请求会拒绝旧的未完成请求。数字更新不延长期限，不需要另建请求。

状态、消费与账号接口

Go SDK 与方法

独立模块 authlink.local/sdk，Go 1.22+，只依赖标准库。适合 Go 网站后台；不需要引入整个 AuthLink 服务端或 MySQL 驱动。

下载 Go SDK 源码包 · 在线查看完整示例 →

安装与初始化

解压后保留 SDK 自己的 go.mod；仅将 SDK 模块接入你的网站项目。

SDK 当前随源码交付，未发布公共 Go module。在你的网站 Go 项目中解压，使用本地 replace：

复制
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

复制
import authlink "authlink.local/sdk"

client, err := authlink.New(authlink.Config{
    Origin:   "https://api.getauthlink.com", // API origin, not the marketing site
    TenantID: os.Getenv("AUTHLINK_TENANT_ID"),
    APIKey:   os.Getenv("AUTHLINK_API_KEY"),
})
if err != nil { return err }

// Get userID and label from your authenticated website session.
state, err := authlink.RandomToken()
if err != nil { return err }
createKey, err := authlink.RandomToken()
if err != nil { return err }
consumeKey, err := authlink.RandomToken()
if err != nil { return err }
// Persist state, both keys and user/session first. Reuse them on retries.
ticket, err := client.CreateRequest(ctx, authlink.CreateInput{
    ExternalUserID: userID, AccountLabel: label,
    Purpose: "bind", State: state,
}, createKey)
if err != nil { return err }
expected := authlink.Expected{
    RequestID: ticket.RequestID, ExternalUserID: userID,
    Purpose: ticket.Purpose, State: state, ExpiresAt: ticket.ExpiresAt,
}
// Save expected and consumeKey before returning the public ticket.

// Load saved expected / consumeKey after checking session, CSRF and ownership.
status, err := client.Status(ctx, expected.RequestID)
if err != nil { return err }
if status.Status == "approved" || status.Status == "consumed" {
    result, err := client.Consume(ctx, expected, consumeKey)
    if err != nil { return err }
    // The SDK has validated the full receipt. Persist a unique confirmation
    // in your own transaction, associated with this user/session and business.
    _ = result
}

Expected 包含 RequestID、ExternalUserID、Purpose、State、ExpiresAt；从后台已保存的请求读取，保持原 expiresAt 字符串。返回类型均带协议 JSON tag，可编码给官方网页组件。SDK 拒绝未知字段、重复键和大小写别名；协议增加字段时需要同步升级 SDK。

等待、取消与错误处理

复制
result, err := client.WaitForConfirmation(ctx, expected, consumeKey, 0)
switch {
case err == nil:
    // Persist result in your own transaction before updating UI or authorizing work.
    _ = result
case errors.Is(err, authlink.ErrRejected):
    // The user rejected the request.
case errors.Is(err, authlink.ErrExpired):
    // The request expired.
case errors.Is(err, context.Canceled), errors.Is(err, context.DeadlineExceeded):
    // This call was canceled or timed out; the platform request is not revoked.
default:
    var api *authlink.APIError
    if errors.As(err, &api) {
        // Handle api.StatusCode / api.Code; retry with the same consumption key.
    }
}

Go 完整示例

示例使用两个阶段：create 创建请求，result 查询并消费已保存的请求。只在用户完成手机确认后执行 result。示例不包含网站的会话管理和数据库持久化，不能直接替代业务授权。

复制// This example creates a request, then queries/consumes a previously saved one.
// 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", "create", "create or result")
	user := flag.String("user", "", "stable user ID from your authenticated session")
	label := flag.String("label", "", "account display label")
	purpose := flag.String("purpose", "bind", "bind or confirm")
	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 "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: *purpose, 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)
	case "result":
		expected := authlink.Expected{RequestID: os.Getenv("AUTHLINK_REQUEST_ID"), ExternalUserID: *user, Purpose: *purpose, State: os.Getenv("AUTHLINK_STATE"), ExpiresAt: os.Getenv("AUTHLINK_EXPIRES_AT")}
		status, err := client.Status(ctx, expected.RequestID)
		if err != nil {
			return err
		}
		if status.Status != "approved" && status.Status != "consumed" {
			return json.NewEncoder(os.Stdout).Encode(status)
		}
		result, err := client.Consume(ctx, expected, os.Getenv("AUTHLINK_CONSUME_KEY"))
		if err != nil {
			return err
		}
		// In a website, persist result atomically with unique request/result IDs,
		// user/session and business association before returning confirmed.
		_ = result
		fmt.Fprintln(os.Stderr, "Receipt validated; this example does not persist or authorize business.")
		return nil
	default:
		return errors.New("mode must be create or result")
	}
}

func main() {
	if err := run(); err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(1)
	}
}

运行参数

后台环境变量

完整示例已包含在 SDK 整包的 examples/quickstart/main.go 中。可复制上方代码保存为 main.go；凭据通过后台环境注入，不要写入代码或浏览器。

复制# Run from a Go project that already includes the SDK module.
# Supply the private environment variables listed above before running.
export AUTHLINK_ORIGIN=https://api.getauthlink.com
go run . -mode create -user stable-user-id -label "Example account" -purpose bind

# After phone approval, load the SAME saved request context before running:
go run . -mode result -user stable-user-id -purpose bind

Node SDK 与方法

复制
// Copy /sdk/node/ and /sdk/browser/ with their relative paths. Server import only.
import { AuthLink, randomToken } from './sdk/node/authlink.mjs';
const auth = new AuthLink({
  origin: 'https://api.getauthlink.com',
  tenantId: process.env.AUTHLINK_TENANT_ID,
  apiKey: process.env.AUTHLINK_API_KEY,
});
// user must come from your authenticated session. This is the creation stage.
const state = randomToken();
const createKey = randomToken();
const consumeKey = randomToken();
// Persist these values and user/session before networking. Reuse on retries.
const ticket = await auth.createRequest({
  externalUserId: user.id, accountLabel: user.displayName,
  purpose: 'bind', state,
}, createKey);
const expected = { requestId: ticket.requestId, expiresAt: ticket.expiresAt,
  externalUserId: user.id, purpose: 'bind', state };
// Save expected, consumeKey and session association before returning ticket.

// Your result endpoint loads the saved request context:
const status = await auth.status(expected.requestId);
if (['approved', 'consumed'].includes(status.status)) {
  const verified = await auth.consume(expected, consumeKey);
  // The SDK has verified the receipt. Persist a unique confirmation atomically.
  // Return verified to the browser only after the database commit succeeds.
}

安装说明、方法参数和使用示例均在本页。Node SDK 与所需依赖已合并为一个压缩包，解压后保留 node 与 browser 的相对目录；网页组件通过 npm 安装。

下载 Node SDK 整包

复制mkdir -p sdk
tar -xzf authlink-node.tar.gz -C sdk
# Import ./sdk/node/authlink.mjs from your backend project.

错误处理

错误 body 为 {"code":"..."}。未知错误不当成成功。接口响应不能共享缓存，禁止记录 bearer、二维码 token、完整证明和原始秘密。