Authentifizierung
Senden Sie Ihren API-Schlüssel als Bearer-Token. Erstellen und verwalten Sie Schlüssel in Ihren Kontoeinstellungen — der vollständige Schlüssel wird nur einmal bei der Erstellung angezeigt, bewahren Sie ihn daher sicher auf.
Authorization: Bearer dpk_live_<selector>_<secret>Schlüssel haben die Form dpk_<env>_<selector>_<secret>, wobei env entweder live oder test ist.
Eine angemeldete Browser-Sitzung kann dieselben Endpunkte aufrufen; sitzungsauthentifizierte Schreibvorgänge erfordern zusätzlich einen X-CSRF-Token-Header. Bearer-Token-Anfragen nicht.
Scopes & Rate-Limits
Jeder Schlüssel trägt eine Reihe von Scopes. Ein Aufruf muss mit einem Schlüssel erfolgen, der den Scope des Endpunkts besitzt. Rate-Limits werden pro Scope und pro Schlüssel angewendet.
| Scope | Berechtigt zu | Rate-Limit | Stufe |
|---|---|---|---|
domain.check |
Check a single .pay domain — availability + pricing | 50/sec | Öffentlich |
catalog.search |
AI keyword search against the curated catalog | 30/min | Öffentlich |
orders.read |
List + read the account's own orders | 60/min | Öffentlich |
orders.write |
Create a pre-order against a saved payment method | 10/min | Öffentlich |
payment_methods.read |
List saved cards (Stripe payment methods) | 20/min | Öffentlich |
payment_methods.write |
Add (SetupIntent) + remove saved cards | 20/min | Öffentlich |
account.read |
Read account profile: email, role, vip_tier, granted scopes | 60/min | Öffentlich |
webhooks.read |
List configured webhook endpoints | 20/min | Öffentlich |
webhooks.write |
Create + delete webhook endpoints | 10/min | Öffentlich |
zone_file.download |
Download the full daily .pay DNS zone-file snapshot | 24/day | Eingeschränkt |
premium.list |
Paginated registry premium catalogue (incl. reserved/blocked) | 60/min | Eingeschränkt |
registered.list |
Paginated registered .pay names (from the DNS zone file) + AI brand context | 60/min | Eingeschränkt |
Eingeschränkte Scopes sind doppelt abgesichert: Ein Schlüssel kann den Scope zwar auflisten, aber Aufrufe gelingen erst, wenn ein Administrator ihn Ihrem Konto gewährt hat. Beantragen Sie ihn in Ihren Kontoeinstellungen.
Unterstützte Domain-Zonen
Ein Konto und ein API-Schlüssel funktionieren in allen Zonen unten — die aufgerufene Basis-URL bestimmt die Zone.
.pay |
https://domain.pay/api/v1 |
.latino |
https://domain.latino/api/v1 |
.dot |
https://domain.dot/api/v1 |
Schnellstart
Zwei schnelle Aufrufe für den Einstieg:
# Einen Namen prüfen
curl -s https://domain.dot/api/v1/check-domain \
-H "Authorization: Bearer dpk_live_…" \
-H "Content-Type: application/json" \
-d '{"domain":"acme.dot"}'
# Wer bin ich + was darf ich
curl -s https://domain.dot/api/v1/account \
-H "Authorization: Bearer dpk_live_…"Endpunkte
Alle Endpunkte sind live. Anfrage- und Antwortschemata, Parameter und Statuscodes sind im OpenAPI-Dokument vollständig beschrieben.
Account
| GET | /account |
account.read |
Your profile + the scopes effective for this key. |
Domains
| POST | /check-domain |
domain.check |
Availability + pricing for one name in a supported zone. Fast DB-only lookup (no live registry call) — POST /orders re-verifies live. |
Catalog
| POST | /catalog/search |
catalog.search |
Keyword search over the curated catalogue. |
Orders
| GET | /orders |
orders.read |
List your orders, newest first. |
| GET | /orders/{id} |
orders.read |
One order + its customer message thread. |
| POST | /orders |
orders.write |
Create a pre-order + charge a saved card (send an Idempotency-Key). |
Payment methods
| GET | /account/payment-methods |
payment_methods.read |
List saved cards. |
| POST | /account/payment-methods |
payment_methods.write |
Start a Stripe SetupIntent to add a card. |
| DELETE | /account/payment-methods/{id} |
payment_methods.write |
Remove a saved card. |
Webhooks
| GET | /webhooks |
webhooks.read |
List webhook endpoints. |
| POST | /webhooks |
webhooks.write |
Register an endpoint (signing secret shown once). |
| DELETE | /webhooks/{id} |
webhooks.write |
Delete an endpoint. |
Restricted
| GET | /zone-file |
zone_file.download |
Daily DNS zone-file snapshot for the zone of the host you call. |
| GET | /premium |
premium.list |
Registry premium catalogue. |
| GET | /registered |
registered.list |
Registered names in the called zone + AI brand context. |
Für den vollständigen Anfrage-/Antwort-Vertrag importieren Sie die OpenAPI-Spezifikation: OpenAPI (JSON) herunterladen.
Webhooks
Registrieren Sie einen HTTPS-Endpunkt, und wir senden signierte Ereignisse, sobald sie eintreten. Das Signaturgeheimnis wird nur einmal bei der Erstellung angezeigt.
| Ereignis | Beschreibung |
|---|---|
order.created | A new order (pre-order) was created on the account |
order.status_changed | An order changed payment status |
payment.succeeded | A payment for an order succeeded |
payment.failed | A payment for an order failed or was canceled |
payment.refunded | A charge for an order was refunded |
appraisal.completed | A domain appraisal for an order finished |
Wir senden den Ereignis-Umschlag per POST als JSON:
{
"id": "evt_…",
"event": "payment.succeeded",
"created": "2026-05-28T12:00:00+00:00",
"data": { "order": { … } }
}Verifizieren Sie jede Zustellung, indem Sie den HMAC-SHA256 über den unveränderten Anfrage-Body mit Ihrem Signaturgeheimnis neu berechnen und in konstanter Zeit vergleichen:
X-Domain-Pay-Signature: sha256=<HMAC_SHA256(raw_body, signing_secret)>Nicht-2xx-Antworten (oder Timeouts) werden mit exponentiellem Backoff (1 min to 24 h) bis zu 6 Mal wiederholt. Nach 5 aufeinanderfolgenden fehlgeschlagenen Zustellungen wird der Endpunkt automatisch deaktiviert und der Eigentümer benachrichtigt.
Fehler
Alle Fehler haben dieselbe Form. Die request_id wird bei jedem Fehler zurückgegeben — geben Sie sie in Support-Anfragen an.
{ "error": "scope_required", "message": "…", "request_id": "req_ab12…", "scope": "orders.read" }| HTTP | error | Bedeutung |
|---|---|---|
| 400 | invalid_request | Malformed or missing parameters. |
| 401 | unauthorized / invalid_key | No or invalid credential. |
| 402 | card_declined / authentication_required | Payment failed or needs SCA. |
| 403 | scope_required | The key lacks the endpoint's scope. |
| 403 | access_not_granted | Restricted scope not yet approved for this account. |
| 403 | csrf_required | Session write without a valid X-CSRF-Token. |
| 404 | not_found | No such endpoint or resource. |
| 405 | method_not_allowed | Wrong HTTP verb. |
| 409 | request_in_progress | An idempotency key's first request is still in flight. |
| 422 | idempotency_key_reused | Same idempotency key, different parameters. |
| 422 | contact_incomplete | GA zones: add a registrant contact under /account/contacts first. |
| 423 | account_locked | Account is locked — contact support. |
| 429 | rate_limited | Slow down; see the Retry-After header. |
| 500 | server_error | Our fault. |
Eingeschränkter Zugriff
Die Endpunkte für Zonendatei, Premium und registrierte Domains benötigen zusätzlich zum Scope eine genehmigte Freigabe:
- Erstellen Sie einen API-Schlüssel (oder verwenden Sie einen vorhandenen), der den eingeschränkten Scope auflistet.
- Öffnen Sie in Ihren Kontoeinstellungen den Eingeschränkten API-Zugriff, wählen Sie den Scope aus und erläutern Sie, wie Sie die Daten nutzen werden.
- Unser Team prüft die Anfrage und teilt Ihnen die Entscheidung per E-Mail mit.
- Nach der Genehmigung kann jeder Schlüssel in Ihrem Konto, der diesen Scope auflistet, ihn sofort verwenden. Keine kostenpflichtige Stufe — die Genehmigung erfolgt pro Konto.