X402.Facilitator.Auth behaviour (X402 v0.5.0)

Copy Markdown View Source

Behaviour for facilitator request authentication.

Some facilitators (for example Coinbase's hosted facilitator, see X402.Facilitator.Auth.CDP) require per-request authentication headers. Implementations of this behaviour build those headers from a stateless config struct created once when the facilitator starts.

Configure a facilitator with the :auth option:

X402.Facilitator.start_link(
  finch: MyFinch,
  url: X402.Facilitator.Auth.CDP.facilitator_url(),
  auth: {X402.Facilitator.Auth.CDP, api_key_id: "...", api_key_secret: "..."}
)

The :auth option accepts either nil (the default, no authentication), a module implementing this behaviour (built with default options), or a {module, opts} tuple.

Implementations are built once at start_link so invalid credentials fail fast, and headers/2 is called once per facilitator operation. Transport retries reuse those headers within the credential's validity window.

Summary

Types

request_info()

Request context passed to headers/2.

t()

Auth implementation state.

Callbacks

headers(t, request_info)

Builds the HTTP headers for a single request.

new(keyword)

Builds auth state from options.

Functions

headers(auth, request_info)

Returns the headers for a request.

new(module)

Normalizes a facilitator :auth option into auth state.

Types

request_info()

@type request_info() :: %{method: :get | :post, host: String.t(), path: String.t()}

Request context passed to headers/2.

The :host is derived from the facilitator base URL and includes the port when present (matching the URL.host semantics used by the CDP SDK). The :path is the full request path — the base URL's path (if any) combined with the operation endpoint (e.g. /platform/v2/x402/verify) — so implementations can bind time-based credentials to the exact request URI.

t()

@type t() :: struct()

Auth implementation state.

Callbacks

headers(t, request_info)

@callback headers(t(), request_info()) ::
  {:ok, [{String.t(), String.t()}]} | {:error, term()}

Builds the HTTP headers for a single request.

Called once per facilitator operation. Returns a list of {name, value} header tuples.

new(keyword)

@callback new(keyword()) :: {:ok, t()} | {:error, term()}

Builds auth state from options.

Called once at start_link time so invalid credentials fail fast. Return {:ok, state} on success or {:error, reason} otherwise.

Functions

headers(auth, request_info)

(since 0.5.0) 
@spec headers(nil | t(), request_info()) ::
  {:ok, [{String.t(), String.t()}]} | {:error, term()}

Returns the headers for a request.

When no auth is configured this returns {:ok, []}.

new(module)

(since 0.5.0) 
@spec new(nil | module() | {module(), keyword()}) ::
  {:ok, nil | t()} | {:error, term()}

Normalizes a facilitator :auth option into auth state.

Accepts:

  • nil — no authentication
  • a module implementing X402.Facilitator.Auth — built with default options
  • {module, opts} — built with the given options