連携先サーバー連携:アカウントと認証コード
現在のフロー:アプリに6桁コードを直接表示
初回はサイトの QR コードを読み取り、App で端末検証を行い、現在のコードをサイトに入力して連携を完了します。次回以降のログインや重要操作は、アカウントの現在のコードをサイトに入力して認証します。
パスワード認証後、連携先サーバー は検証待ちセッションを保存し、コード検証の成功後に正式なログイン権限を付与します。重要操作はそれぞれ検証します。
連携先サーバー は検証待ちフォームを保存して権限を確認し、コード検証の成功後に応答と対応する業務操作を同じトランザクションで確定します。
連携に必要な3つの主要API
初回連携の作成、アカウント状態の照会、コード検証には次の3つのAPIを使用します。
externalUserId は連携先内で一意かつ固定の連携先ユーザーIDで、表示可能なASCII文字1〜128文字です。cid-username を使う場合は一意性と継続性を確保します。表示名は accountLabel です。
連携先認証情報はサーバーで保持
API Origin にはデプロイ設定の AUTHLINK_ORIGIN を使用します。全連携 API で連携先の 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 です。連携先サーバー 側のユーザー利用状態も確認します。
初回のQR連携
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分間有効です。スキャン、コード取得、再試行で期限は延長されず、6桁のコードは引き続き最長1分間有効です。accountLabel は必須、UTF-8で160バイト以内で、制御文字は禁止です。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 は先頭のゼロを保持した6桁の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に一意制約を設け、元のフォーム操作と同じトランザクションで記録します。フロントのコールバックは表示更新専用です。
失敗、再試行、1回限りの使用
アプリは元の端末の新しい署名をオンライン検証し、最大1分有効の6桁コードを取得します。表示中のアカウントで期限後に自動更新し、オフライン時は再試行を表示します。新しいコードで古いコードは失効し、使用済みコードは別操作に使えません。
5分間で誤ったコードまたは再利用コードを5回送ると、以降は 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は端末の不一致です。
同じ操作・キー・コードには同じ応答を返します。有効期間は1分で、expiresAt に示します。連携先サーバー はコードエラーを検証失敗、通信や応答の異常をサービス障害として処理します。
上記はAuthLink APIのHTTPステータスとエラーコードです。本文は {"code":"ERROR_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)
}
}