Domain setup

DNS records

Use a subdomain you control, such as login.acme.ca for a live app or login-dev.acme.ca for a test app. Apex domains such as acme.ca aren’t accepted: a CNAME can’t sit at the apex. Creating an app returns dns_records, two records to publish at your DNS host:

; At your DNS host, for login.acme.ca
_honkio-auth.login.acme.ca.  TXT    "honkio-auth=<the token from dns_records>"
login.acme.ca.               CNAME  edge.signin.honkio.ca.

Verify

Once the records are published, verify. The dashboard checks the records live as you go; the API checks on each call and says which records it found:

curl -X POST https://api.honkio.ca/v1/auth-apps/APP_ID/domain/verify \
  -H "Authorization: Bearer mk_test_YOUR_KEY"
# → { "domain_status": "PENDING_CERT", "found": { "txt": true, "cname": true } }

DNS changes can take a while to spread. Verify as often as you like; nothing is lost while you wait.

HTTPS certificate

HonkIO serves HTTPS on your hostname through Cloudflare for SaaS, which issues and renews the certificate: there’s nothing to upload or renew. A certificate is only ever requested for a hostname whose TXT proof is verified, never for a hostname that merely points at HonkIO. If certificate setup is briefly unavailable, verify answers 503 AUTH_APP_DOMAIN_UNAVAILABLE; try again shortly.

Cloudflare-proxied DNS

If your DNS is on Cloudflare with the proxy (the orange cloud) turned on for the sign-in hostname, a public lookup shows Cloudflare’s addresses instead of the CNAME. That’s fine: HonkIO decides whether traffic reaches it from the hostname’s status at Cloudflare, not from a public DNS lookup, so proxied hostnames verify and stay active. The TXT record is never proxied.

If you’d rather keep it simple, set the sign-in hostname to DNS only (the grey cloud).

Daily checks

HonkIO checks every hostname daily. If traffic no longer reaches HonkIO, the app is marked INACTIVE and you’re emailed; sign-in can’t work then anyway. If only the TXT record is gone, HonkIO keeps serving the page, because stopping would lock your users out. You’re warned daily, and after 14 days the app is flagged for HonkIO staff to review. Put the TXT record back to clear it.

Changing the hostname

An app can move to a new hostname in place: it keeps its users, client ID and secret. Send PATCH /v1/auth-apps/:id with hostname on its own. The new hostname waits in pending_hostname with its own TXT record (the CNAME target is the same); publish both, then verify with POST /v1/auth-apps/:id/domain/verify. The app keeps serving on the old hostname until the switch, which happens once the TXT proof passes and the certificate is issued.

• At the switch the issuer changes with the hostname, so every session and refresh token ends, and tokens issued for the old hostname stop being accepted. Users sign in again.
• Passkeys tied only to the exact old hostname stop working (passkeys tied to your whole domain keep working). If passkeys would then be the only sign-in method on, the API refuses the move with AUTH_APP_HOSTNAME_CHANGE_NEEDS_FALLBACK: turn on email or text sign-in first.
• Cancel a pending move with DELETE /v1/auth-apps/:id/hostname-change. A move whose certificate isn’t issued within 14 days of the proof is cancelled for you, and you’re emailed.
• From the dashboard (Domains), changing the hostname asks you to confirm it’s you first (a step-up); from a dashboard session the API answers AUTH_APP_STEP_UP_REQUIRED without one.

Rules

• One app per hostname. A hostname another app has proven answers 409 AUTH_APP_HOSTNAME_TAKEN.
• Deleting an app releases its hostname at once and stops serving it. Attaching that hostname to another app takes a new TXT proof, so nobody can claim a forgotten CNAME that still points at HonkIO.
• Apex domains, HonkIO’s own domains and malformed names answer 422 AUTH_APP_HOSTNAME_INVALID.
• Because the sign-in page is on your domain, cookies your site sets for the whole domain (Domain=.acme.ca) reach it too. HonkIO never reads, stores or logs any cookie except its own __Host-hk_ cookies, and its request logs drop the Cookie header entirely. HonkIO’s cookies are host-only, so it never sets a cookie for your domain.