Integrator server integration: accounts and passcodes
Current flow: six-digit codes directly in the app
For initial binding, scan the website QR code, complete device verification in the app, and enter the current app code on the website. Successful website verification completes binding. For later sign-ins and sensitive actions, enter the account’s current code on the website.
After password authentication, the integrator server saves a pending session and grants full sign-in access after successful code verification. Verify each sensitive action separately.
The integrator server saves the pending form, checks user permissions, and commits the verification receipt and corresponding operation in one transaction after successful code verification.
Three core integration endpoints
Use the following three endpoints to create an initial binding, query account status and verify a code.
externalUserId is a unique, stable user identifier within the integrator’s system, containing 1–128 visible ASCII characters. A cid-username combination must be unique and remain fixed. accountLabel is the display name.
Keep integrator credentials on the server
Use the AUTHLINK_ORIGIN from your service configuration as the API origin. All integration endpoints require an Authorization: Bearer integrator key. Passcode verification and enrollment creation also require a stable Idempotency-Key; retries of the same operation must reuse it.
Account binding status
POST /v1/integration/accounts/status
{"externalUserId":"user-100"}The integrator server obtains externalUserId from its session. unbound means unbound, bound means bound, and deleted means permanently revoked.
Success returns HTTP 200. platform is null for unbound or deleted and android or ios for bound. The integrator server also checks its own user-enabled state.
First enrollment
POST /v1/integration/requests
{"externalUserId":"user-100","accountLabel":"Demo account","purpose":"bind","state":"<43-character random token>"}The backend independently generates state and the creation idempotency key, then returns qr and expiresAt to the current session. After scanning and device verification, the user enters the current app code in the integrator client, and the backend calls auth to complete binding.
Successful binding creation returns HTTP 200 with requestId, qr, qrSvg, purpose and expiresAt. The initial scan ticket lasts 60 minutes from creation. Scanning, fetching codes and retries do not extend its deadline; each six-digit App code still lasts at most one minute. accountLabel is required, limited to 160 UTF-8 bytes, and must contain no control characters. Set purpose to bind. Generate state and Idempotency-Key independently, each from 32 cryptographically random bytes encoded as unpadded Base64URL (43 characters).
Creating a fresh binding for an already bound externalUserId returns HTTP 409 / ACCOUNT_ALREADY_BOUND; a revoked account returns HTTP 409 / ACCOUNT_UNAVAILABLE. Retrying the original creation key and parameters may return the original unexpired ticket. Reusing a key with changed parameters returns IDEMPOTENCY_CONFLICT; an expired original ticket returns REQUEST_EXPIRED (both HTTP 409).
Optional: query binding progress by requestId
GET /v1/integration/requests/{requestId}
Authorization: Bearer <integrator API key>Returns requestId, status and expiresAt. pending awaits phone verification; approved awaits code entry on the website; consumed indicates completed verification; rejected indicates rejection; expired indicates expiry. AccountStatus is authoritative for the final binding state.
Verify a passcode directly
POST /v1/integration/auth
Idempotency-Key: <saved key for this integrator server action>
{"externalUserId":"user-100","passcode":"001234"}passcode is a six-digit ASCII string preserving leading zeros. The backend obtains externalUserId from the current session and saves the form’s association with its pending action.
{
"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"
}The backend SDK checks the user, integrator, policy, receipt ID and expiry. Your website must also store verificationId uniquely and commit it with the original form action in the same transaction. Frontend callbacks only update the UI.
Failures, retries and one-time use
The App gets a six-digit one-time code online after verification of a fresh signature from the original device. Codes last at most one minute and refresh when the current account page is visible. Offline errors show Retry. New codes invalidate old codes; used codes cannot authorize another operation.
After five incorrect or reused-code attempts per account within a five-minute window, subsequent verification returns PASSCODE_LOCKED. Counting resets when the window ends. Integrator or request rate-limit violations return 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 means incorrect code; PASSCODE_EXPIRED means expired or replaced; PASSCODE_USED means already used; PASSCODE_LOCKED means too many attempts. ACCOUNT_NOT_BOUND means not enrolled; ACCOUNT_UNAVAILABLE means revoked; APPROVAL_REQUIRED means initial device verification is incomplete; KEY_MISMATCH means device mismatch.
The same operation, key and code return the same receipt. Receipts last one minute, as specified by expiresAt. The integrator server displays code errors as verification failures and treats network or response errors as service failures.
The HTTP statuses and codes above are AuthLink API responses. Error bodies use {"code":"ERROR_CODE"}. Refer to the list above for meanings.
The integrator server validates and uniquely stores verificationId, committing it with the pending action before receipt expiry. Keep a fixed key for each action. After a definitive verification failure, allow another code; if the network result is unknown, retry the original code and key.
Permanently revoke a binding
POST /v1/integration/accounts/delete
{"externalUserId":"user-100"}Success returns status: deleted and permanently revokes the user’s AuthLink binding. The integrator manages its own users separately.
Go SDK: verify a passcode
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: verify a passcode
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)
}
}