Get transfer-out auth code

GET /v1/domain-purchases/:id/auth-code

Returns the EPP/auth code the end-user needs to transfer the domain to another registrar (GoDaddy, Cloudflare, wherever they want).

Sensitive — treat the response like a password. Anyone with the auth code can move the domain out. Don't log it, don't store it, hand it to the end-user securely.

Request

curl https://api.domainee.dev/v1/domain-purchases/f8a0c1b9-…/auth-code \
  -H "Authorization: Bearer $DOMAINEE_API_KEY"

Response — 200 OK

{
  "hostname": "janesbakery.com",
  "authCode": "X8k!Q2pZv9Mn"
}

Errors

Code	Status	When
not_found	404	Purchase doesn't exist in this workspace.
Registrar error	502	Some TLDs require the auth code be emailed to the registrant; Namecheap may decline to surface it via API for those. Surface the registrar's error in your UI.

What happens after you hand it over

1. Your end-user takes the auth code to the destination registrar.
2. They initiate a transfer-in. The destination registrar contacts our registrar to verify the code.
3. ICANN sends an email to the listed registrant asking them to approve the transfer (5-day window).
4. If approved, the domain leaves Domainee's reseller account and moves to the destination. We mark our purchase row but the underlying domain is no longer managed here.

Side effects

• No charge.
• No DB write.
• The auth code is not cached — every call hits the registrar fresh.

Notes

• The domain must be unlocked at the registrar before a transfer goes through, and new domains are locked by default. There is no unlock endpoint yet: email support@domainee.dev with the hostname and we clear the lock for you. registrarLocked on GET /:id/details shows the current state.
• ICANN blocks transfers for 60 days after a new registration (and after a previous transfer), regardless of the lock. Plan the UI around that.
• For some TLDs the registrar emails the code to the registrant instead of returning it here, so handle the 502 case in your UI.
• This is the "escape hatch" — every customer of every SaaS deserves it. Even if you never expect anyone to transfer out, exposing this endpoint builds the trust that "I really do own this domain".