Domains — DNS verification & create

Register a tenant domain in IBEx: request a DNS TXT challenge (no auth), publish the record, then call PUT /domains with a user JWT to verify DNS and obtain rpId, apiKey, and primaryRpId.

These endpoints are not under /v1.2 — they use the root path /domains/... on the same API host (e.g. https://passkeys-prat1.ibex.fi).

What you are proving

IBEx stores each partner app as a Domain row keyed by rpId (typically your WebAuthn / app hostname, e.g. app.example.com).
Before the row is trusted for production, you must prove control of DNS for that hostname using a one-time TXT token.

Step 1 — `GET /domains/dns-challenge` (public)

Auth: none — safe to call from a script or browser without a JWT.

Query

Parameter	Required	Description
`domain`	Yes	FQDN to verify (e.g. `app.example.com`). Lowercased server-side.

Example

curl -sS "https://passkeys-prat1.ibex.fi/domains/dns-challenge?domain=app.example.com"

Response (200) — create this DNS TXT record at your DNS provider:

Field	Meaning
`record`	Hostname for the TXT record (e.g. `_ibex-verify.app.example.com`)
`value`	Full TXT value to set (starts with `ibex-verify=` + random token)
`type`	Always `TXT`
`ttl`	Challenge lifetime in seconds (about 1 hour); token is stored in Redis

The server stores the expected token until it expires. If you skip this step, PUT /domains will fail with “call GET /domains/dns-challenge first”.

Step 2 — Publish the TXT record

In your DNS zone, add a TXT record:
- Name / host: as returned in record (often the subdomain _ibex-verify.<your-domain>).
- Value: exactly the string in value (including the ibex-verify= prefix).
Wait for DNS propagation (minutes to hours depending on TTL and provider).
Optionally verify with dig TXT <record> or an online DNS checker before calling step 3.

Step 3 — `PUT /domains` (JWT)

Auth: Authorization: Bearer <access_token> for a user who should become admin of the new domain (the API connects that user to the Domain after creation).

Headers

Header	Value
`Authorization`	`Bearer <access_token>`
`Origin` or `rpId`	Must allow the API to resolve an existing tenant context where applicable (same rules as other authenticated routes).

Body (JSON)

Field	Required	Description
`domain`	Yes	Same FQDN you used in step 1 (after DNS is visible to the API server).
`primaryRpId`	No	Omit to link the new domain to the default primary `rpId` configured on the server. Set to `null` for a standalone domain (no ROR link). Set to another existing standalone domain’s `rpId` for ROR (related origins).

Example (standalone)

curl -sS -X PUT "https://passkeys-prat1.ibex.fi/domains" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain":"app.example.com","primaryRpId":null}'

What the server does

Loads the challenge for domain from Redis (must still be valid).
Performs a DNS TXT lookup on _ibex-verify.<domain> and checks that one of the TXT strings exactly matches the expected ibex-verify=<token> value.
Creates a new Domain (or upgrades an auto-created unverified domain) with dnsVerified = true, sets primaryRpId from the rules above, and attaches the authenticated user as domain admin.
Returns:

Field	Description
`rpId`	Tenant identifier (same as `domain` when created fresh).
`apiKey`	Tenant API key — store securely; used as `x-api-key` on API calls for that `rpId`.
`primaryRpId`	Linked primary for ROR, or `null` if standalone.

After creation

Use x-api-key: <apiKey> together with correct Origin / rpId resolution on versioned routes (/v1.2/...).
Optional: GET /system/health with x-api-key returns rpId and signerCount when the key is valid — handy to confirm the key without hitting a protected route (see internal system docs).

Common errors

Symptom	Likely cause
No challenge / bad request	Did not call GET /domains/dns-challenge first, or challenge expired (~1 h).
DNS TXT not found	Propagation delay, wrong host, or record not created at public DNS.
Verification failed	TXT value mismatch (extra quotes, spaces, or wrong token).
Domain already exists	Domain row already verified — use admin flows to change settings instead.
JWT errors	Missing/expired token on PUT /domains only — step 1 stays public.