Server integration

Integration flow and trust boundaries

1. The operator creates a separate tenant for your website and delivers its credentials to your backend.
2. The backend obtains a stable user ID from the signed-in session and generates random state, a creation key and a separate consumption key.
3. Create a bind / confirm request, save the user, session, purpose, state, requestId, expiresAt and keys, then return only the public ticket to the browser.
4. The user checks the website, account and code in AuthLink, then approves the request.
5. On approved / consumed, the backend calls consume using the saved state and consumption key.
6. Validate the receipt and persist a unique requestId / verificationId record in your own database transaction before returning confirmed. Protected business endpoints check that record.

There is no webhook.approved, six-digit codes and frontend callbacks cannot directly authorize business actions. AuthLink does not receive action, amounts, transactionHash or permission scopes.

Tenants and authentication

Obtain your site’s tenantId, apiKey, origin and expiresAt from the operator. New keys never expire; the operator can still rotate or revoke keys or disable the tenant. Existing keys keep their original expiry. Store keys securely on your backend only.

Create requests and parameters

POST /v1/integration/requests · API origin：

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

Success returns HTTP 200 and a ticket:

A new request for the same account rejects its unfinished requests. Code refreshes do not extend expiry or require a new request.

Status, consumption and account APIs

Go SDK and methods

Independent module authlink.local/sdk, Go 1.22+, standard library only. For Go website backends, without importing the AuthLink server or MySQL driver.

Download Go SDK source · Read the complete example →

Install and initialize

Keep the SDK’s own go.mod after extracting it. Add only the SDK module to your website project.

The SDK ships as source and has no public Go module release yet. Extract it in your website project and use a local replace directive:

Copy
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

Copy
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 contains RequestID, ExternalUserID, Purpose, State and ExpiresAt. Load it from the saved backend request and preserve the exact expiresAt string. Response structs have protocol JSON tags for the official web components. Unknown fields, duplicate keys and case aliases are rejected; update the SDK when protocol fields change.

Waiting, cancellation and errors

Copy
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.
    }
}

Complete Go example

The example has two stages: create creates a request; result queries and consumes the saved request. Run result only after phone approval. The example does not implement website sessions or database persistence and does not authorize business actions.

Copy// 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)
	}
}

Command-line options

Backend environment variables

The SDK archive includes this example at examples/quickstart/main.go. You can also copy the code above into main.go. Supply credentials through the backend environment, never in source code or the browser.

Copy# 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 and methods

Copy
// 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.
}

Installation, method options and usage examples are on this page. The Node SDK and its dependency are in one archive. Preserve the relative node and browser directories after extraction; install web components through npm.

Download the Node SDK archive

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

Error handling

Error body: {"code":"..."}. Never treat unknown errors as success. Do not share-cache API responses or log bearer keys, QR tokens, complete proofs or raw secrets.