Claim Flow

The screen between “I created the record” and “proved” is where most verification flows lose people. This guide builds one that says something true at every moment.

Claim, and show the record

try {
  const domain = await ownsi.domains.findOrCreate(name)
  return await domain.claim()
} catch (error) {
  if (isOwnsiError(error) && error.code === "already_claimed") return useExistingClaim()
  throw error
}

The record on the claim is what to render — host, name, type and value. It is null once the claim has ended, because there is nothing left to write.

<Field label="Type" value={claim.record.type} />
<Field label="Host" value={claim.record.host} copy />
<Field label="Value" value={claim.record.value} copy />

Copy host, not name. Almost every panel appends the zone to what you type, and a copy button that hands over the fully qualified name is how people end up with domain_appended. Offer name as a secondary “fully qualified” affordance for the panels that want it.

Poll the verification, not the claim

The claim only moves once, at the end. What changes while someone waits is the process behind it, and the claim knows which one that is.

hooks/useVerificationState.ts

export const useVerificationState = (claimId: string) =>
  useQuery({
    queryKey: ["verification", claimId],
    queryFn: async () => (await ownsi.claims.get(claimId)).verification(),
    refetchInterval: (query) => nextPoll(query.state.data),
  })

const RUNNING = new Set(["checking", "propagating", "needs_attention"])

const nextPoll = (verification?: Verification) => {
  if (!verification || !RUNNING.has(verification.status)) return false
  if (verification.waitEstimate) {
    return Math.min(verification.waitEstimate.secondsRemaining, 30) * 1_000
  }
  return 5_000
}

Deriving the interval from waitEstimate.secondsRemaining means the client asks roughly when there is something new to hear, instead of every five seconds forever.

POST /api/verifications/:id/runs forces a run and is rate limited per verification. Wire it to a button the person presses, not to a timer. Nothing about asking more often makes DNS answer sooner, and the honest interval is already on the verification.

One message, from two fields

A verification that has not proved always carries exactly one of diagnosis or waitEstimate, and they mean opposite things.

export const whatNow = (verification: Verification) => {
  if (verification.status === "proved") return { kind: "done" as const }

  if (verification.diagnosis) {
    return {
      kind: "fix" as const,
      title: verification.diagnosis.cause,
      action: verification.diagnosis.fix,
      code: verification.diagnosis.code,
    }
  }

  return {
    kind: "wait" as const,
    title: waitTitle(verification.waitEstimate),
    seconds: verification.waitEstimate?.secondsRemaining ?? null,
  }
}

Render cause and fix verbatim — they already name your domain, your token and your nameservers. Do not pattern-match on their text; they are product copy and change. Key anything behavioural off code.

Style the three groups differently

Not every diagnosis is your reader’s fault, and treating them alike is the mistake worth avoiding.

Fix it

domain_appended · record_at_apex · value_formatted · record_on_www · no_matching_record · record_absent · cname_conflict · expired_tokenPrimary action, prominent. fix is a real instruction. expired_token is the cheapest of them: the record is in the right place and only its value is stale.

Wait

negative_cache · not_publishedCalm, with the countdown. No action button — there is nothing to press.

Escalate

servfail · lame_delegation · foreign_tokenPoint at the provider or the other account. Not something retyping the record will fix.

Status drives the frame around it

`verification.status`	Frame
`checking`	The record, and the first-run countdown.
`propagating`	”Your nameservers have it.” Wait, not a fix.
`needs_attention`	The diagnosis, front and centre.
`proved`	The date on `claim.endedAt`, and `domain.proof()` if the name proved before.
`exhausted`	The window closed. One button to claim again — a new token, one edit in the panel.
`stopped`	The claim was canceled, or its domain archived. No action.

propagating versus needs_attention is the split that earns the product its keep — both are “not verified”, but only one is your reader’s problem.

Do not tell people to delete the record

Leaving it in place is the supported state. A later claim on the same name issues a new token, so the record already in the zone comes back as expired_token rather than as nothing found: the person edits one value instead of working out where the record goes again. Telling them to delete it turns that one-line edit back into the whole task. Archiving does not retract a proof either — every proof keeps its date. It does take back the links published from it, which is the point of archiving rather than a side effect of it.

Using the API

Endpoints

Clients

Guides

Claim, and show the record

Poll the verification, not the claim

One message, from two fields

Style the three groups differently

Fix it

Wait

Escalate

Status drives the frame around it

Do not tell people to delete the record

​Claim, and show the record

​Poll the verification, not the claim

​One message, from two fields

​Style the three groups differently

Fix it

Wait

Escalate

​Status drives the frame around it

​Do not tell people to delete the record

Claim, and show the record

Poll the verification, not the claim

One message, from two fields

Style the three groups differently

Status drives the frame around it

Do not tell people to delete the record