Référence API

Authentification

Toutes les requêtes API nécessitent une authentification via une clé API. Transmettez la clé dans l’en-tête Authorization en tant que token Bearer. La clé API doit commencer par le préfixe nxd_.

Authorization: Bearer nxd_your_api_key_here

La couche d’authentification API est sans état – chaque requête est authentifiée indépendamment. Il n’y a ni sessions ni cookies.

Gardez votre clé API secrète. Ne la partagez pas dans du code côté client, des dépôts publics ou des URL. Si une clé est compromise, révoquez-la immédiatement et créez-en une nouvelle.

Erreurs d’authentification

Format de réponse

Toutes les réponses sont en JSON. Les réponses réussies ont la structure suivante :

Ressource unique

{
    "status": "success",
    "data": {
        "id": 42,
        "public_id": "xK9mP2",
        "name": "example.com",
        ...
    }
}

Liste paginée

{
    "status": "success",
    "data": [ ... ],
    "meta": {
        "total": 150,
        "page": 1,
        "per_page": 25,
        "last_page": 6
    }
}

Réponse d’erreur

{
    "status": "error",
    "error": {
        "code": "validation_error",
        "message": "Validation failed.",
        "details": {
            "name": ["Domain name is required."]
        }
    }
}

Identifiants publics

Chaque ressource est identifiée par un id opaque (par exemple xK9mQ2), utilisé dans les chemins d’URL. Les identifiants numériques de la base de données ne sont jamais exposés ni acceptés.

Pagination des listes

Les points de terminaison de liste qui renvoient des résultats paginés acceptent les paramètres de requête suivants :

Zones DNS

Gérez les zones DNS. Nécessite zones.read pour les opérations de lecture et zones.write pour les opérations d’écriture.

GET /v1/zones

Liste toutes les zones de l’utilisateur authentifié.

Paramètres de requête

• search – filtrer les zones par nom
• page, per_page – paramètres de pagination

Champs de réponse

Champs : id, name, type (master/slave), status, ns_group, created_at, updated_at

GET /v1/zones/{id}

Obtenir des informations détaillées sur une zone spécifique, y compris les données SOA, les serveurs de noms et le nombre d’enregistrements.

Champs de réponse supplémentaires

records_count, soa (primary_ns, admin_email, serial, refresh, retry, expire, minimum), nameservers (tableau), ns_group (id, slug, name)

POST /v1/zones

Créer une nouvelle zone DNS. La création de zones est bloquée si l’utilisateur a des factures en retard.

Corps de la requête (JSON)

{
    "name": "example.com",
    "type": "master",
    "ns_group_id": 1,
    "master_ip": ""
}

• name (obligatoire) – nom de domaine
• type – "master" (par défaut) ou "slave"
• ns_group – groupe NS auquel assigner la zone (optionnel, utilise le groupe par défaut si omis)
• master_ip – obligatoire pour les zones secondaires ; doit être une adresse IP valide

Renvoie 201 Created avec l’objet zone.

DELETE /v1/zones/{id}

Supprimer une zone et tous ses enregistrements.

Renvoie 204 No Content en cas de succès.

GET /v1/zones/{id}/export

Exporter une zone au format BIND ou en JSON structuré.

Paramètres de requête

• format – "bind" (par défaut) renvoie le texte du fichier de zone BIND ; "json" renvoie un tableau structuré d’enregistrements avec name, type, content et ttl

Enregistrements

Gérez les enregistrements DNS au sein d’une zone. Tous les points de terminaison des enregistrements sont imbriqués sous une zone. Nécessite records.read pour les opérations de lecture et records.write pour les opérations d’écriture.

GET /v1/zones/{zoneId}/records

Liste tous les enregistrements d’une zone.

Paramètres de requête

• type – filtrer par type d’enregistrement (ex. : A, CNAME, MX)
• name – filtrer par nom d’enregistrement (correspondance de sous-chaîne)
• search – rechercher dans le nom et le contenu

Champs de réponse

id, name, type, content, ttl, disabled, fields (champs analysés spécifiques au type)

GET /v1/zones/{zoneId}/records/{recordId}

Obtenir un enregistrement unique par son identifiant.

POST /v1/zones/{zoneId}/records

Créer un nouvel enregistrement DNS.

Corps de la requête (JSON)

{
    "type": "A",
    "name": "www",
    "ttl": 3600,
    "content": "93.184.216.34"
}

• type (obligatoire) – type d’enregistrement (A, AAAA, CNAME, MX, TXT, SRV, CAA, NS, PTR, ALIAS, DNAME, DS, TLSA)
• name – nom de l’enregistrement relatif à la zone (par défaut : @ pour l’apex de la zone)
• ttl – durée de vie en secondes (par défaut : 3600)
• content – valeur de l’enregistrement (IP pour A/AAAA, nom d’hôte pour CNAME/NS/PTR, texte pour TXT, serveur de messagerie pour MX)

Champs spécifiques au type

• MX : priority (par défaut : 10)
• SRV : priority, weight, port
• CAA : flags (par défaut : 0), tag (par défaut : "issue")
• DS : keytag, algorithm, digest_type
• TLSA : usage, selector, matching_type

Renvoie 201 Created avec l’objet enregistrement.

PUT /v1/zones/{zoneId}/records/{recordId}

Mettre à jour un enregistrement existant. N’incluez que les champs que vous souhaitez modifier ; les champs omis conservent leurs valeurs actuelles.

{
    "content": "93.184.216.35",
    "ttl": 7200
}

Renvoie 200 OK avec l’objet enregistrement mis à jour. Remarque : l’identifiant de l’enregistrement peut changer après une mise à jour car il est calculé à partir du nom, du type et du contenu de l’enregistrement.

DELETE /v1/zones/{zoneId}/records/{recordId}

Supprimer un enregistrement de la zone.

Renvoie 204 No Content en cas de succès.

DNSSEC

Gérez DNSSEC pour vos zones. Nécessite zones.read pour consulter le statut et zones.write pour activer ou désactiver.

GET /v1/zones/{id}/dnssec

Obtenir le statut DNSSEC d’une zone, y compris les clés et les enregistrements DS.

Champs de réponse

enabled (booléen), keys (tableau d’enregistrements DNSKEY), ds_records (tableau d’enregistrements DS à configurer auprès du bureau d’enregistrement)

POST /v1/zones/{id}/dnssec/enable

Activer DNSSEC pour une zone. Génère automatiquement les clés de signature.

Renvoie le statut DNSSEC avec les clés générées et les enregistrements DS.

POST /v1/zones/{id}/dnssec/disable

Désactiver DNSSEC pour une zone. Supprime toutes les clés de signature.

Renvoie {"enabled": false, "keys": [], "ds_records": []}.

Groupes NS

Liste les groupes de serveurs de noms disponibles. Utilisez l’id d’un groupe comme ns_group lors de la création d’une zone. Toute clé d’API valide peut lire cet endpoint.

GET /v1/ns-groups

Liste les groupes de serveurs de noms actifs.

Champs de réponse par groupe

id, name, slug

Compte

Consulter les informations du compte et gérer les clés API.

GET /v1/account

Obtenir les informations du compte actuel, y compris les détails de l’abonnement.

Champs de réponse

Champs : id (UUID), email, name, role, status, language, timezone, created_at

subscription – objet avec plan, billing_cycle, status, current_period_start, current_period_end (ou null si aucun abonnement)

GET /v1/account/api-keys

Liste toutes les clés API de l’utilisateur authentifié.

Champs de réponse par clé

id, name, key_prefix (8 premiers caractères), permissions (tableau), last_used_at, expires_at, created_at

POST /v1/account/api-keys

Créer une nouvelle clé API.

Corps de la requête (JSON)

{
    "name": "CI/CD Pipeline",
    "permissions": ["zones.read", "records.read", "records.write"],
    "expires_at": "2027-01-01"
}

• name (obligatoire) – nom lisible (max. 255 caractères)
• permissions (obligatoire) – tableau de permissions (au moins une requise) : zones.read, zones.write, records.read, records.write, webhooks.read, webhooks.write
• expires_at – date d’expiration optionnelle (ISO 8601 ou YYYY-MM-DD) ; doit être dans le futur

La réponse inclut la clé API complète dans le champ key. C’est la seule fois où la clé complète est renvoyée. Stockez-la en lieu sûr.

Renvoie 201 Created avec les détails de la clé, y compris la valeur complète de la key.

DELETE /v1/account/api-keys/{id}

Révoquer (supprimer définitivement) une clé API.

Renvoie 204 No Content en cas de succès.

Facturation

Consulter l’abonnement, les plans et les factures. Ces points de terminaison sont en lecture seule.

GET /v1/billing/subscription

Obtenir les détails de l’abonnement actuel. Renvoie null si aucun abonnement actif.

Champs de réponse

Champs : id, plan, billing_cycle, status, current_period_start, current_period_end, created_at

GET /v1/billing/plans

Liste tous les plans disponibles avec les tarifs et les fonctionnalités.

Champs de réponse par plan

id, name, slug, description, price_monthly, price_yearly, currency, max_domains, max_records, features (tableau)

GET /v1/billing/invoices

Liste les factures de l’utilisateur authentifié, les plus récentes d’abord.

Paramètres de requête

• status – filtrer par statut (draft, issued, sent, void)
• page, per_page – paramètres de pagination

GET /v1/billing/invoices/{id}

Obtient une facture via son <code>id</code>.

Champs de réponse

Champs : id, number, status, amount (TTC), net_amount (HT), tax_amount, tax_rate, currency, issued_at, created_at. Les montants sont des chaînes décimales simples.

Webhooks

Gérez les abonnements webhook sortants pour recevoir des notifications en temps réel sur les modifications de zones et d’enregistrements. Nécessite webhooks.read pour la lecture et webhooks.write pour créer, modifier ou supprimer.

GET /v1/webhooks

Liste tous les abonnements webhook de l’utilisateur authentifié.

Champs de réponse par webhook

id, url, events (tableau), description, is_active, failure_count, last_triggered_at, created_at

POST /v1/webhooks

Crée un abonnement webhook.

Corps de la requête (JSON)

{
    "url": "https://example.com/webhook",
    "events": ["zone.created", "record.created"],
    "description": "Production webhook"
}

• url (obligatoire) – endpoint HTTPS qui recevra les charges utiles des événements
• events (obligatoire) – tableau des types d’événements auxquels s’abonner
• description – libellé lisible facultatif

La réponse inclut un secret pour vérifier les signatures de webhook (HMAC). C’est la seule fois où le secret est renvoyé. Conservez-le en lieu sûr.

Renvoie 201 Created avec l’id et le secret du webhook.

GET /v1/webhooks/{id}

Obtient un abonnement webhook avec ses livraisons les plus récentes.

PUT /v1/webhooks/{id}

Met à jour un abonnement webhook. N’incluez que les champs à modifier.

Renvoie 200 OK avec l’objet webhook mis à jour.

DELETE /v1/webhooks/{id}

Supprime un abonnement webhook.

Renvoie 204 No Content en cas de succès.

POST /v1/webhooks/{id}/test

Envoie un événement de test à l’endpoint du webhook pour vérifier qu’il est joignable.

Met en file d’attente une livraison de test avec une charge utile "type": "test".

Types d’événements disponibles

Abonnez-vous à n’importe quelle combinaison de ces types d’événements :

zone.created, zone.deleted, record.created, record.updated, record.deleted, dnssec.enabled, dnssec.disabled, zone.health.problem, zone.health.resolved

Codes d’erreur

Toutes les erreurs suivent un format cohérent avec un code d’erreur sous forme de chaîne et un message lisible.

Exemples de code

Tous les exemples utilisent curl. Remplacez nxd_your_api_key par votre clé API réelle.

Lister vos zones

curl -s "https://api.nexdns.tech/v1/zones" \
    -H "Authorization: Bearer nxd_your_api_key"

Créer une zone

curl -s -X POST "https://api.nexdns.tech/v1/zones" \
    -H "Authorization: Bearer nxd_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{"name": "example.com"}'

Ajouter un enregistrement A

curl -s -X POST "https://api.nexdns.tech/v1/zones/{zoneId}/records" \
    -H "Authorization: Bearer nxd_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
        "type": "A",
        "name": "www",
        "ttl": 3600,
        "content": "93.184.216.34"
    }'

Ajouter un enregistrement MX

curl -s -X POST "https://api.nexdns.tech/v1/zones/{zoneId}/records" \
    -H "Authorization: Bearer nxd_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
        "type": "MX",
        "name": "@",
        "ttl": 3600,
        "content": "mail.example.com",
        "priority": 10
    }'

Mettre à jour un enregistrement

curl -s -X PUT "https://api.nexdns.tech/v1/zones/{zoneId}/records/{recordId}" \
    -H "Authorization: Bearer nxd_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{"content": "93.184.216.35", "ttl": 7200}'

Supprimer un enregistrement

curl -s -X DELETE "https://api.nexdns.tech/v1/zones/{zoneId}/records/{recordId}" \
    -H "Authorization: Bearer nxd_your_api_key"

Exporter une zone (format BIND)

curl -s "https://api.nexdns.tech/v1/zones/{zoneId}/export" \
    -H "Authorization: Bearer nxd_your_api_key"

Activer DNSSEC

curl -s -X POST "https://api.nexdns.tech/v1/zones/{zoneId}/dnssec/enable" \
    -H "Authorization: Bearer nxd_your_api_key"

Créer une clé API

curl -s -X POST "https://api.nexdns.tech/v1/account/api-keys" \
    -H "Authorization: Bearer nxd_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "Read-only key",
        "permissions": ["zones.read", "records.read"],
        "expires_at": "2027-12-31"
    }'

Obtenir les informations du compte

curl -s "https://api.nexdns.tech/v1/account" \
    -H "Authorization: Bearer nxd_your_api_key"