Discovery Document

How the SDK finds the server's signing requirements automatically.

Before signing a request, the SDK fetches <origin>/.well-known/erc8128 to discover what signing options the server requires. The result is cached per origin for the lifetime of the client.

Example document

json

{
  "label": "sigauth",
  "replayable": false,
  "binding": "request-bound",
  "ttlSeconds": 60,
  "endpoints": [
    { "pattern": "/api/demo/echo", "methods": ["POST"] }
  ]
}

Fields

Field	Type	Description
label	string	Signature label. Must match "sigauth" for AuthProof middleware.
replayable	boolean	Whether the server accepts replayable signatures. Always false in production.
binding	"request-bound" \| "none"	Whether the signature covers the full request (method, path, body).
ttlSeconds	number	Maximum acceptable age of a signature in seconds.
endpoints	array (optional)	List of endpoint patterns the document applies to.

401 retry flow

If the server returns a 401 with an accept-signature header, the SDK automatically re-signs the request using the server's preferred options and retries once.

This allows servers to upgrade signing requirements (e.g., switch from replayable to request-bound) without breaking existing clients.

Serving the document in Next.js

typescript

// apps/web/app/api/well-known/erc8128/route.ts
export async function GET() {
  return Response.json({
    label: "sigauth",
    replayable: false,
    binding: "request-bound",
    ttlSeconds: 60,
    endpoints: [{ pattern: "/api/demo/echo", methods: ["POST"] }]
  });
}