REST API

Base URL: https://app.dodomain.io. Every request and response body is JSON.

Everything on this page is also published machine-readably as an OpenAPI 3.1 document at https://dodomain.io/docs/openapi.json — generated from the same schemas these endpoints validate with, and regenerated by a CI gate that fails on any drift.

Authentication

Two credential kinds, for two different callers:

• Secret key (dd_sk_...) — server-to-server. Create an app in the dashboard to get one; send it as Authorization: Bearer dd_sk_... from your server only. A missing, malformed, or unknown key returns 401 unauthorized. The public key (dd_pk_...) only identifies the app and grants nothing.
• Session token (dd_sess_...) — a single-session capability returned by POST /api/v1/sessions. Session-scoped endpoints are public and authorize by the unguessable token itself, which is how the hosted flow and widget work from the browser. Sessions expire after 24 hours; expired sessions answer 410 expired.

Endpoints

Creating a session

POST /api/v1/sessions takes the domain and the records the end user must create. The response tells you what the session will actually be verified against:

{
  "id": "cmd...",
  "token": "dd_sess_...",
  "expiresAt": "2026-08-13T09:00:00.000Z",
  "connectUrl": "https://app.dodomain.io/connect/dd_sess_...",
  "records": [{ "type": "CNAME", "host": "app", "fqdn": "app.customer.com" }]
}

records echoes each record you sent alongside fqdn — the fully-qualified name DoDomain will look up on authoritative DNS. Hosts are composed relative to the session's domain, and @ (or an empty host) means the domain itself.

When something about an accepted request is worth flagging, the response also carries warnings. Warnings never change the status code — the session is created either way — and the key is absent when there is nothing to say:

{
  "warnings": [
    {
      "code": "duplicate_host_label",
      "message": "host \"links\" repeats the leading label of domain \"links.acme.com\" — this session will be verified at \"links.links.acme.com\". Use host \"@\" if you meant \"links.acme.com\".",
      "host": "links",
      "fqdn": "links.links.acme.com"
    }
  ]
}

Branch on code, not on the message text. New codes may be added; treat an unrecognised one as informational.

Reading a session

GET /api/v1/sessions/:token is the debugging endpoint: it echoes back exactly what we stored for a session, so you can confirm the API received what you think you sent. It is authorized by the session token itself (no secret key), and returns 410 expired once the session's 24 hours are up.

{
  "id": "cmd...",
  "domain": "customer.com",
  "records": [{ "type": "CNAME", "host": "app", "value": "cname.sendly.io" }],
  "recipe": null,
  "status": "pending",
  "tier": null,
  "detectedProvider": null,
  "returnUrl": null,
  "expiresAt": "2026-08-13T09:00:00.000Z"
}

Reading a session by id (server-side)

GET /api/v1/sessions/:token needs the session token and stops answering once the session expires. When you are reconciling from a webhook — every payload carries sessionId, never the token — or you want to know how a session ended, call the same path with the session id and your secret key instead:

curl https://app.dodomain.io/api/v1/sessions/cmd... \
  -H "Authorization: Bearer dd_sk_..."

One path, two arms: a dd_sess_... segment is the public token read above, anything else is this authenticated by-id read. A key only sees its own app's sessions; a session that exists but belongs to another app answers the same 404 not_found as one that doesn't exist.

{
  "id": "cmd...",
  "appId": "cmd...",
  "domain": "customer.com",
  "records": [{ "type": "CNAME", "host": "app", "fqdn": "app.customer.com" }],
  "recipe": null,
  "status": "verifying",
  "tier": 3,
  "detectedProvider": "cloudflare",
  "connectionId": null,
  "createdAt": "2026-08-16T09:00:00.000Z",
  "expiresAt": "2026-08-17T09:00:00.000Z",
  "expired": false
}

Unlike the token endpoint, this one keeps answering 200 after expiry — reading a session's final state is most of the reason to call it.

Re-checking DNS yourself

POST /api/v1/sessions/:token/verify is a supported thing to call from your own code, not just something the hosted flow does. It runs a live authoritative DNS check of the session's records and, when every record matches, finalizes the connection and fires connection.verified + session.completed — the same path a user clicking Verify takes.

curl -X POST https://app.dodomain.io/api/v1/sessions/dd_sess_.../verify

{
  "verified": false,
  "records": [
    {
      "fqdn": "app.customer.com",
      "type": "CNAME",
      "present": false,
      "note": "no CNAME found at app.customer.com",
      "outcome": "absent"
    }
  ]
}

It is authorized by the session token (no secret key), it is safe to call repeatedly, and calling it on an already-verified session does not double-count your quota. outcome distinguishes absent (we looked, it isn't there) from indeterminate (the lookup itself failed) and domain_not_found (the domain doesn't resolve at all) — only a real authoritative match ever finalizes.

You usually don't need to poll it. DoDomain already re-checks open sessions in the background, so a record added after the user closes the connect window still completes on its own (see Webhooks). Call verify when you want an answer now — for example while a support agent is on the phone with the customer.

Managing webhook endpoints

Everything the dashboard's Webhook endpoints card does is also a REST call, so delivery targets can live in your CI or infrastructure-as-code instead of in someone's browser history. These endpoints take the app's secret key only: an OAuth token (the credential AI assistants connect with) is refused with 403 forbidden and details.code: "SECRET_KEY_REQUIRED", because no consent scope covers managing your credentials.

POST /api/v1/webhook-endpoints with {"url": "https://your-app.com/webhooks/dodomain"} answers 201:

{
  "id": "cme...",
  "appId": "cmd...",
  "url": "https://your-app.com/webhooks/dodomain",
  "createdAt": "2026-08-17T09:00:00.000Z",
  "secret": "whsec_..."
}

PATCH /api/v1/webhook-endpoints/:endpointId takes the same {"url": ...} body and moves an endpoint without re-keying it — a receiver that changed hosts keeps verifying with the secret it already has. POST /api/v1/webhook-endpoints/:endpointId/rotate-secret is the explicit re-key: it returns the same object shape as create, with a new secret. Rotation is immediate and total — signatures switch to the new secret at once, including retries of deliveries that were queued before you rotated, so deploy the new secret to your handler promptly.

DELETE /api/v1/webhook-endpoints/:endpointId answers {"id": "...", "deleted": true}. Past deliveries keep their history, but a failed delivery to a deleted endpoint can no longer be redriven.

Failures use the same codes the rest of the API does:

Rotating your secret key

POST /api/v1/keys/rotate rotates the secret key that authenticated the call and returns the replacement once:

{
  "appId": "cmd...",
  "publicKey": "dd_pk_...",
  "secretKey": "dd_sk_...",
  "rotatedAt": "2026-08-17T09:00:00.000Z",
  "previousKeyExpiresAt": null
}

The public key is echoed unchanged: it identifies the app in the widget and is never rotated.

By default there is no overlap window — with no body (or {"overlapHours": 0}) the key you called with stops authenticating the moment this returns, so this response is the only copy of the new key. Write it to your secret store before your next API call. That default is deliberate: if a key leaked, rotating it must be the revoke, never a grace period.

Opt-in zero-downtime rotation: send {"overlapHours": 1} or {"overlapHours": 24} and BOTH keys authenticate until previousKeyExpiresAt (returned as an ISO timestamp), so your servers can pick up the new key with no failed requests in between. Two things to know about the window:

• Exactly one previous key is ever kept. Rotating again — with or without a window — replaces the previous slot, so key n-1 stops working instantly regardless of how much window it had left. Chain rotations no faster than your rollout.
• A zero-overlap rotate ends any live window. Rotating with the default overlapHours: 0 (or no body) kills the previous key along with installing the new one — it is the escape hatch when a key you gave a window to turns out to be compromised.

The dashboard's API-keys card shows a live window's expiry and when the old key last authenticated a request, so you can see when your cutover is actually complete before the window ends.

A rotation from a scheduled job, using GitHub Actions and the gh CLI to write the new key back:

#!/usr/bin/env bash
set -euo pipefail

response="$(curl -fsS -X POST https://app.dodomain.io/api/v1/keys/rotate \
  -H "Authorization: Bearer ${DODOMAIN_SECRET_KEY}")"

new_key="$(printf '%s' "$response" | jq -er '.secretKey')"

# Store FIRST, verify SECOND: the old key is already dead at this point.
gh secret set DODOMAIN_SECRET_KEY --body "$new_key"

curl -fsS https://app.dodomain.io/api/v1/webhook-endpoints \
  -H "Authorization: Bearer ${new_key}" > /dev/null
echo "rotated $(printf '%s' "$response" | jq -r '.appId')"

Rate limits and quotas

Secret-key requests are rate-limited per app on a fixed one-minute window, by plan. Over the cap, requests fail with 429 rate_limited, a Retry-After header (seconds), and details.retryAfterSeconds in the body.

The monthly connections number is a billing quota, not a rate limit: on every plan it is enforced at session creation (402 quota_exceeded once your team is at its cap). Connections you already have keep working — only new sessions are refused.

What counts against it: exactly one unit, the first time a session's connection is finalized. Re-verifying, a connection breaking and recovering, and disconnecting and reconnecting the same session all add nothing — the quota counts connections made, not verifications run. A connection created in an earlier month that recovers today counts against neither month again.

Session-scoped endpoints (/api/v1/sessions/:token/...) are public — the token is the credential — so they carry their own abuse caps instead of the plan's: one per client address, and a higher ceiling per session across all addresses. Both answer with the same 429 rate_limited shape. Normal use, including the hosted flow's automatic re-check every 15 seconds, sits far below either.