サーバー連携

連携フローと信頼境界

1. 運営者がサイト専用のテナントを作成し、認証情報をサイトのバックエンドへ渡します。
2. バックエンドがログイン済みセッションから安定したユーザー ID を取得し、ランダムな state と作成用・消費用の冪等キーを生成します。
3. bind / confirm リクエストを作成し、ユーザー、セッション、用途、state、requestId、expiresAt、冪等キーを保存します。その後、公開 ticket のみをブラウザーに返します。
4. ユーザーが AuthLink でサイト、アカウント、数字を照合し、リクエストを承認します。
5. approved / consumed を取得したら、保存済みの state と消費用キーで consume を呼び出します。
6. 受領結果を検証し、自分のデータベースのトランザクションで requestId / verificationId を一意に保存してから confirmed を返します。保護対象の処理はこの記録を確認します。

webhook はありません。approved、6 桁の数字、フロントエンドのコールバックだけで処理を許可してはいけません。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 を返します。

同じアカウントの新しいリクエストは、未完了の古いリクエストを拒否します。数字の更新で有効期限は延長されず、リクエストの再作成も不要です。

状態・消費・アカウント API

Go SDK とメソッド

独立したモジュール authlink.local/sdk。Go 1.22 以降に対応し、標準ライブラリーのみを使用します。Go 製サイトのバックエンド向けで、AuthLink サーバーや MySQL ドライバーの導入は不要です。

Go SDK のソースをダウンロード · 完全なサンプルを読む →

インストールと初期化

展開後も SDK 自身の go.mod を保持し、サイトのプロジェクトには SDK モジュールのみを組み込んでください。

SDK はソースで配布しており、公開 Go モジュールは未リリースです。サイトの 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 の元の文字列を保持してください。戻り値の構造体には公式 Web コンポーネント向けの JSON タグがあります。未知のフィールド、重複キー、大文字小文字の別名は拒否します。仕様のフィールド変更時は 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 の相対パスを保持し、Web コンポーネントは 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":"..."}。未知のエラーを成功として扱わないでください。API レスポンスの共有キャッシュは禁止です。bearer キー、QR token、証明全体、秘密情報をログに残さないでください。