Registrar integration packet
HeadlessDomains Registrar Handoff Packet
Registrar engineering, operations, and certification teams evaluating HeadlessDomains before EPP.
Current Status
HTTP registrar API sandbox is available for controlled testing. This is not production registrar approval and not an EPP endpoint.
- Version
- 0.1
- Updated
- 2026-06-11
- Base URL
https://partners.headlessdomains.com/api/v1/registrar/v1
Prerequisites
1.Approved registrar channel in HeadlessDomains Partners.
2.Partner API key using the registrar_api profile and bound to the registrar channel.
3.Approved namespace listing for the registrar channel and requested test TLD.
4.Server-side client that keeps bearer tokens out of browser, mobile, and public logs.
5.Named technical and support contacts for escalation.
Current Commands
GET /statusVerify registrar channel, namespace listings, production approval, scopes, rate limits, and registry service capabilities.POST /sandbox/resetReset predictable OT&E fixtures without overwriting real domains.POST /domains/checkCheck availability for a full SLD or label/TLD pair.POST /domainsCreate a registration through the internal registry service.GET /domains/{domain}Read registration, namespace, lifecycle, backend, and nameserver state.POST /domains/{domain}/renewRenew a registration with idempotent retry safety.PATCH /domains/{domain}Update registrant metadata or supported lifecycle status fields.POST /domains/{domain}/transferRecord transfer intent and queue backend/EPP apply when needed.PUT /domains/{domain}/nameserversStore desired nameserver state and queue backend apply when needed.DELETE /domains/{domain}Cancel a lifecycle record; this is not a hard delete.GET /pollRead recent command audit events for reconciliation.Required Test Sequence
1.Run GET /status and archive the response before any mutating test command.
2.Reset sandbox fixtures with POST /sandbox/reset.
3.Run availability check for a known available name.
4.Create a test registration and retry the same request with the same idempotency key.
5.Read the created registration and fixture registrations.
6.Renew the renewal fixture and confirm retry safety.
7.Patch registrant metadata on the update fixture.
8.Record transfer intent on the transfer fixture and confirm retry safety.
9.Set nameservers on the nameserver fixture and confirm backend_apply_status is visible.
10.Cancel the delete fixture and confirm retry safety.
11.Poll command logs and reconcile command ids, idempotency keys, statuses, and timestamps.
12.Record the reviewed run as a named OT&E run in /admin/interop, then export the run archive after review.
Evidence Required
1.API client name, registrar channel, and test namespace.
2.GET /status output showing channel approval, approved namespace listings, production status, command capabilities, rate-limit state, and registry service contract.
3.Request ids or idempotency keys for every required command.
4.HTTP status codes and response bodies for first attempt and retry attempt.
5.Poll output proving HeadlessDomains audit rows match registrar-side command records.
6.Poll output must include audit row id and registrar.channel_id matching GET /status audit_provenance.registrar_channel_id.
7.Named OT&E run archive from /admin/registrar-ote-runs/<run_id>/evidence-archive.md, including its archive fingerprint SHA-256.
8.Confirmation that bearer tokens were never exposed client-side or in public logs.
9.Support escalation contact for failed provisioning, ownership disputes, and customer migration questions.
Boundaries
1.This packet covers HTTP registrar integration before EPP.
2.EPP compatibility will be a later gateway on top of the same registry service.
3.Nameserver and cancellation commands may remain pending backend apply until the namespace backend supports automated apply.
4.Protected legacy/NB recovery records must not be reopened for resale without an explicit recovery decision.
5.Production credentials require commercial approval, namespace-owner approval, support readiness, rate-limit agreement, and launch signoff.