GFAVIP sign-in and the existing customer domain API
Status, November 18, 2026: Wallet and Headless Domains backend changes are released. Both storefronts require PKCE. Real sign-in is reported successful on both sites; live portfolio display and two-buyer acceptance remain pending.
Use the existing GFAVIP customer login, Headless Domains domain API and Partners sales integration. This adds no reseller programme, service, credential type, customer mapping or portfolio database. AgentID's organization reseller API remains its existing integration for organization-managed domains.
Which guide to use
Use the standard GFAVIP Wallet SSO guide as the canonical login contract: enrollment, browser-bound state, S256 PKCE, exchange validation, server sessions and logout. This guide covers the Headless Domains settings, customer domain response and storefront acceptance. Share these two links with an implementing agent rather than copying a separate login protocol.
Stage 1 checkout, recovery and management handoffs remain unchanged. Keep Stage 2 behind its feature flag until live portfolio display and the acceptance checks below pass. Local tests and synthetic buyers do not establish live acceptance.
Fixed settings and Wallet enrollment
| Wallet service ID | Exact callback | New-registration suffix |
|---|---|---|
tx-domains |
https://tx.domains/auth/gfavip/callback |
.tx |
hey-id |
https://hey.id/auth/gfavip/callback |
.hey |
Both existing Wallet SSO entries are active and enrolled with the exact service IDs/callbacks above and Require S256 PKCE and exact service/callback binding enabled. Their CORS entries already exist. Operators can review these settings in Wallet SSO administration; do not create another entry or disable PKCE to work around a client error.
Live authorization checks on November 16 confirmed that missing PKCE, missing state and a plain challenge method are rejected; wrong service/callback values are rejected; valid S256 requests reach Wallet login on both sites. This verifies the provider boundary, not the storefront's callback or customer portfolio UI.
Existing apps retain their behavior until enrolled. The migration adds callback lists, an enforcement flag and a challenge column to existing tables; it does not automatically enroll clients. Server-to-server exchange/domain calls do not need CORS. No catalog publication or Partners key is required for this buyer read flow.
Existing Wallet code flow
Follow the shared browser-bound S256 code flow and server implementation requirements, using this storefront's fixed service/callback from the table above. In particular:
- Save fresh state and verifier on the server, bound to the browser initiating login. Validate and atomically consume that attempt before exchanging the code.
- Exchange server-to-server with the saved verifier and exact service/callback.
Require
pkce_verified === true, matching service/callback,user_idandtokenbefore rotating the local session. Identity never comes from the URL. - Keep the GFAVIP token server-side. Treat it as an opaque bearer; never construct it from a user ID, add a prefix or put it in browser storage or logs.
Session authority and explicit logout
Follow the Wallet session and logout contract. The bearer is a full GFAVIP account session, with a fixed 30-day expiry for these storefronts. It is not read-only, application-scoped or suffix-scoped. Use ordinary customer accounts for acceptance, never team/superadmin accounts. Review this trust model before public rollout; test-account restrictions do not narrow production credentials.
On explicit logout, revoke the exact server-held session through Wallet's existing
POST /api/auth/sso/revoke, then clear local state. Always clear local state on
failure too, but report remote revocation as unconfirmed. Wallet browser-cookie
logout is a separate operation. The canonical guide documents both.
Existing Headless Domains API
Call from the authenticated storefront backend:
GET https://headlessdomains.com/api/v1/domains?include_recovered=true
Authorization: Bearer <server-held-GFAVIP-customer-token>
The existing authentication derives the buyer from that token, preserving existing
managed-agent access. Do not send an owner ID or use an organization credential for
this buyer list. include_recovered=true adds activated, verified legacy claims
using the same loader as the dashboard. No domain migration is necessary.
The response remains {"status":"success","data":[...]}. There is no client
pagination or namespace parameter here; the loader follows upstream holder pages
and fails if it cannot complete them. Default/false preserves the previous native
and purchase list without depending on the holder service. The organization-key
branch and its grants/customer mapping are unchanged.
Native-domain fields are unchanged. Partners rows retain id, name, tld,
status, owner_id, expiry_date, source, order_id and management_path.
With the recovered-name option:
| Field | Meaning |
|---|---|
source |
headlessdomains_partners_marketplace for a purchase; headlessdomains_partners_holder_claim for a recovered name |
id |
Existing partners:<registration-id> format |
claim_activated |
Whether the holder claim activated; purchase-only rows may be false |
entitlement_expires_at |
Verified customer entitlement expiry, or null |
registry_backend_expires_at |
Registry term, or null; not the customer's renewal deadline |
expiry_date |
Recorded expiry, or null when unknown; never infer one year from purchase |
management_path |
Relative Headless Domains destination; resolve against https://headlessdomains.com |
A purchase also present in the holder projection appears once, keeping its purchase ID/link and adding verified entitlement fields. Pending claims do not appear as active recovered names. Preserve unknown dates and distinguish entitlement from registry terms in the UI.
Both storefronts may display the buyer's authorized .tx and .hey names.
Filter results server-side using the fixed allowlist {tx, hey} and return only
display-safe fields to the browser. A suffix filter never establishes ownership;
start with the authenticated buyer's API result. Restrict new registrations to
the site's suffix shown above. This is display filtering: the existing
GFAVIP session retains its account permissions. A read-only page does not make the
credential read-only or restrict it to one suffix. No new token system is introduced.
Responses are private/no-store. 401 requires authentication. A disabled,
misconfigured or failed holder projection returns 503 portfolio_unavailable
without partial data. Do not interpret that as “no domains.” Invalid option values
return 400 invalid_include_recovered. Distinguish loading, confirmed empty,
login-expired and unavailable states.
Synthetic response example
This is a synthetic example matching the released endpoint's response shape, produced through the API handler with isolated fixtures. It is not a captured customer response and does not prove any live account has these records. All names and identifiers below are invented. The first row is a marketplace purchase; the second is an activated legacy claim.
{
"data": [
{
"claim_activated": false,
"directory_listed": true,
"entitlement_expires_at": null,
"expiry_date": null,
"grace_ends_at": null,
"id": "partners:synthetic-purchase-registration",
"is_listed": true,
"management_path": "/dashboard/marketplace-domain/synthetic-order",
"name": "synthetic-purchase.tx",
"order_id": "synthetic-order",
"owner_id": "synthetic-buyer",
"registry_backend_expires_at": null,
"source": "headlessdomains_partners_marketplace",
"status": "active",
"tld": "tx"
},
{
"claim_activated": true,
"directory_listed": true,
"entitlement_expires_at": "2027-11-01T00:00:00",
"expiry_date": "2027-11-01T00:00:00",
"grace_ends_at": null,
"id": "partners:synthetic-claim-registration",
"is_listed": true,
"management_path": "/dashboard/claim-domain/synthetic-claim-registration",
"name": "synthetic-legacy.hey",
"order_id": null,
"owner_id": "synthetic-buyer",
"registry_backend_expires_at": "2030-01-01T00:00:00",
"source": "headlessdomains_partners_holder_claim",
"status": "active",
"tld": "hey"
}
],
"status": "success"
}
Parse the top-level status and data array, not a domains property. Preserve
string IDs (including the partners: prefix), full source values and null fields.
An activated claim can have order_id: null; a purchase-only row can have
claim_activated: false. Both are valid records. Resolve management_path against
https://headlessdomains.com; do not navigate it relative to the storefront.
Timestamps can be returned without a timezone suffix: do not require a trailing
Z or invent timezone precision that the record does not provide.
Native-domain rows retain their existing field set and may lack Partners-specific source, order, claim or management fields. Do not reject the whole portfolio because a native row fails a schema written only for Partners rows. Apply the fixed suffix display filter after successfully parsing the authenticated result.
Troubleshooting a dashboard 503
Successful Wallet identity verification and a failed domain dashboard are separate steps. Establish where the failure occurred before changing login or enrollment:
- On the storefront server, record the UTC time, requested API path, upstream HTTP status, content type and failure stage. Keep the status returned by Headless Domains separate from the status your storefront returns to its browser. Record a request correlation ID when available, without logging authorization headers, tokens, codes, buyer IDs, names or response bodies.
- If Headless Domains returns
401, investigate the server-held customer session and require sign-in as appropriate. If it returns503 portfolio_unavailable, report the UTC window and redacted correlation evidence to Headless Domains for investigation of authentication, purchase loading and activated-claim loading. Preserve the unavailable state; never substitute an empty list. - If Headless Domains returns
200but the storefront returns503, inspect response reading, JSON parsing, schema validation, filtering and rendering on the storefront. Check the wrapper, source values, prefixed IDs, nullable fields, relative management paths, date formats and native rows described above. Report validation field paths and reason codes only, without field values. - Exercise the parser and UI with the synthetic example, including both rows. Then repeat with two authorized ordinary buyers on both live storefronts. Synthetic parsing proves contract handling, not live ownership or completeness.
A 200 in upstream access logs establishes the API status, not the exact contents
of an unlogged response or whether the storefront displayed it. If no matching
request is found, say so; use an authorized existing test account with known
purchase and activated-claim coverage if available, and record any missing
coverage as pending. Do not make purchases or activate claims just to create a
production fixture. Keep credentials and customer data out of support messages.
Provider rollout and acceptance
Released provider revisions: Wallet 5c24cc20 (PR #26)
and Headless Domains 34ff95e3 (PR #158).
Both Railway application deployments succeeded. Headless Domains' existing holder
projection is enabled and configured; its API key stays on Headless Domains.
The domain API rejects unauthenticated requests. This work does not change TLD
custody, delegation, DNS or registration.
Backend automated tests use isolated databases and synthetic buyers through real routes/queries, with mocked upstream identity/holder responses on Headless Domains. They verify backend behavior, not live cross-service acceptance. Arrange an isolated test environment or authorized existing ordinary customer accounts with known purchases and activated claims. Newly issued accounts are unnecessary if suitable existing accounts are available. Empty accounts and synthetic local claims do not establish live purchase/claim coverage; record missing coverage as pending. Do not purchase or activate production names merely to create a fixture. Deliver test access securely, never in chat or this guide. A gated testing URL and redacted evidence are sufficient; private repository access is not required.
| Check | Required result |
|---|---|
| Buyer A: purchase and activated claim | Both appear once with correct terms |
| Buyer B: separate purchase | Each sees only their authorized names |
| Pending claim | Not shown as an active recovered name |
| Wrong browser state or code from another attempt | No local session created |
| Wrong callback/service, missing/wrong verifier | Rejected |
| Expired/reused code or parallel exchange | At most one successful exchange |
| Missing hardened fields | Rejected for both enrolled storefronts |
| Holder service failure | Unavailable, not empty/partial success |
| Both storefronts | Real login; only the buyer's authorized .tx and .hey names |
| Reload, safe deep link, logout | Correct local lifecycle and exact-session Wallet revocation |
| Wallet unavailable during logout | Local session cleared; remote revocation unconfirmed |
Keep Stage 1 checkout, recovery and management handoffs working. Enable Stage 2 only after both storefronts pass. Rollback disables Stage 2, retaining existing records and Stage 1. No private repository access is needed: provide revisions and redacted results, distinguishing mocked evidence from live tests.
Copyable task for Nole's agent
Reuse the existing storefront, GFAVIP authorize/exchange endpoints and server
session. The provider changes are live. Keep Stage 2 behind its test/feature flag
until real sign-in and two-buyer acceptance pass on both sites.
Use https://wallet.gfavip.com/docs for the shared login/session/logout contract
and https://docs.headlessdomains.com/guides/storefront-sso-portfolio/ for the domain
response example, troubleshooting and acceptance checklist.
Implement state + S256 PKCE using this site's fixed service/callback. Bind each
attempt to the browser, reject invalid state, consume it once, and exchange
server-to-server with the saved verifier. Require pkce_verified true and matching
service/callback. Use exchange.user_id as identity. Keep the existing GFAVIP token
server-side and rotate the local session. These are full account sessions, not
read-only credentials. Use ordinary customer test accounts, never team/admin.
On explicit logout call Wallet POST /api/auth/sso/revoke with that session bearer,
then clear local state. If revocation fails, clear local state but report remote
revocation as unconfirmed.
Call GET https://headlessdomains.com/api/v1/domains?include_recovered=true with
that customer token. Filter server-side to the fixed {tx, hey} display allowlist;
keep new registrations restricted to each site's suffix. Handle 401, 503,
null expiry, source/entitlement fields and returned management paths. Do not turn
errors into empty success or accept browser-supplied owner IDs. Parse status/data,
string IDs and nullable fields; allow native rows without Partners-only fields.
If our API is 200 but your dashboard is 503, trace body reading, parsing, schema
validation, filtering and rendering. Share only upstream status and sanitized
failure stage/reason codes, never response values or customer identifiers.
Keep the dashboard read-only and retain registration, management and recovery
handoffs. Add no reseller account system, token type, portfolio database or
provider endpoint. Supply redacted acceptance results and storefront revisions;
no private repository or credentials need to be shared.