伺服器端接入

接入流程與信任邊界

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、完整證明和原始秘密。