API CNF · v1

Vue d’ensemble

La version 1 permet d’effectuer des opérations DNS sur les zones que vous avez revendiquées depuis la gestion DNS. Créez et révoquez des jetons dans Compte → Clés d’API.

URL de base et gestion des versions

https://api.c.nf/v1

Tous les points de terminaison se trouvent sous /v1. Toute modification incompatible utilisera un nouveau chemin de version majeure. Des champs et points de terminaison rétrocompatibles pourront être ajoutés à la v1 et seront consignés dans le journal des modifications.

Authentification et portées

Toute requête qui lit ou modifie des données de compte doit inclure un jeton Bearer. Les jetons commencent par cnf_, suivi de 32 caractères hexadécimaux.

curl https://api.c.nf/v1/dns/zones \
  -H "Authorization: Bearer cnf_a1b2c3d4e5f60718293a4b5c6d7e8f90"

Les jetons sont stockés sous forme de hachages à sens unique et leur valeur complète n’est affichée qu’à leur création. Si vous perdez un jeton, révoquez-le et créez-en un autre.

Chaque jeton possède des portées. Un jeton sans portée configurée reçoit dns:read par défaut. La portée d’écriture autorise également la lecture.

En cas de portée incompatible, l’API renvoie 403 forbidden_scope et inclut required_scopes ainsi que token_scopes pour faciliter le diagnostic.

Isolation entre utilisateurs

Un jeton Bearer correspond à un seul user_id. Chaque gestionnaire de zone vérifie la revendication validée de cet utilisateur avant toute lecture ou écriture. Il n’existe ni dérogation administrateur, ni mécanisme d’usurpation, ni contournement entre utilisateurs.

Même un jeton doté de * ne peut agir que sur les zones vérifiées de son propre utilisateur. Toute tentative d’utiliser la zone d’un autre compte renvoie 403 forbidden_zone.

Enveloppe de réponse

Réponse réussie

{
  "success": true,
  "data": { "zones": [] },
  "request_id": "req_abc123def456abcd"
}

Réponse d’erreur

{
  "success": false,
  "error": "forbidden_zone",
  "message": "zone not verified for this account (or does not exist)",
  "request_id": "req_abc123def456abcd",
  "zone": "example.com"
}

request_id figure dans chaque réponse et peut être enregistré sans risque dans les journaux côté client.

Codes d’erreur

Vérification des zones

Lorsque POST /v1/dns/zones revendique une zone, le serveur choisit l’une des méthodes suivantes :

1. Vérification instantanée (method: "auto") — Utilisée si aucun autre compte n’a revendiqué la zone. La revendication est immédiatement vérifiée. Les enregistrements ne font autorité qu’après que le propriétaire a dirigé la délégation NS du bureau d’enregistrement vers les serveurs de noms renvoyés.
2. Vérification TXT — Utilisée pour une revendication contestée. Ajoutez la valeur TXT renvoyée à _cnfdns-verify.<zone>, puis appelez POST /v1/dns/zones/{zone}/verify.
3. Ancienne vérification NS — Les anciennes revendications en attente peuvent utiliser verify_method: "ns". La vérification compare les réponses NS publiques de la zone avec le jeu de serveurs de noms attendu.

La vérification est idempotente. La répéter pour une revendication déjà vérifiée renvoie verified: true sans modifier la revendication.

Types d’enregistrements et limites

Types d’enregistrements pris en charge

A, AAAA, CNAME, MX, TXT, NS, SRV, CAA, PTR, SPF.

priority est obligatoire pour MX et SRV, et ignoré pour les autres types. ttl doit être compris entre 60 et 2 592 000 secondes.

Points de terminaison

Services publics

De petits points d’accès fiables et sans compte : heure, adresse, pays, taux de change et empreintes.

Compte

À qui appartient un jeton et ce qu’il permet de faire.

DNS

Revendiquez un domaine, prouvez que vous le contrôlez, puis gérez ses enregistrements.

Identifiants

Le coffre d’identifiants privé derrière l’outil du même nom.

Fichiers

Stockage personnel : lister, envoyer, modifier, partager et supprimer.

CDN

Mise en cache en périphérie et trafic de vos fichiers partagés.

Transfert de SMS

Les messages relayés depuis votre téléphone, et les clés qui l’autorisent.

Sites statiques

Envoyez un zip, servez un site.

Déploiements

Vos points d’accès formulaire, webhook et lien court déployés.

Domaines

Votre portefeuille de domaines et ses données d’enregistrement.

Paquets

Publiez des versions et consultez leurs versions et totaux de téléchargement.

WHOIS

Données d’enregistrement d’un domaine, mises en cache et partagées avec les outils de domaines.

Pour les agents IA

Orientez un agent vers /v1/ai pour un résumé conçu pour être collé tel quel dans une invite, ou vers /v1/ai?format=json pour les mêmes points d’accès sous forme de définitions d’outils. /v1/openapi.json est le contrat OpenAPI 3.1 complet et /llms.txt la carte destinée aux robots. Les quatre sont générés depuis la même table de routes que cette page : aucun ne peut décrire un point d’accès inexistant.

curl https://api.c.nf/v1/ai
curl https://api.c.nf/v1/ai?format=json
curl https://api.c.nf/v1/openapi.json

Champs de requête

Créer une revendication de zone

Créer un enregistrement DNS

Modifier un enregistrement DNS

Exemples

curl -H "Authorization: Bearer $CNF_TOKEN" \
  https://api.c.nf/v1/dns/zones

curl -X POST https://api.c.nf/v1/dns/zones \
  -H "Authorization: Bearer $CNF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"zone":"example.com"}'

curl -X POST https://api.c.nf/v1/dns/zones/example.com/verify \
  -H "Authorization: Bearer $CNF_TOKEN"

curl -X POST https://api.c.nf/v1/dns/zones/example.com/records \
  -H "Authorization: Bearer $CNF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"A","host":"api","value":"192.0.2.10"}'

Démarrage rapide

1. Créez une clé d’API avec dns:write dans Compte → Clés d’API, puis copiez-la lorsqu’elle s’affiche.
2. Stockez le jeton dans une variable d’environnement protégée sur votre machine.
3. Appelez GET /v1/account/me pour vérifier le jeton et ses portées.
4. Revendiquez une zone. La réponse indique si la vérification est instantanée, fondée sur TXT ou fondée sur l’ancienne méthode NS.
5. Effectuez la preuve DNS renvoyée lorsqu’elle est requise, puis appelez le point de terminaison de vérification.
6. Ne créez, consultez, modifiez ou supprimez des enregistrements qu’une fois la revendication vérifiée.

Journal des modifications

v1.1.0 — gestion des zones

• Ajout des revendications de zone par API, avec vérification instantanée ou par TXT.
• Ajout de l’état d’une zone et de points de terminaison de vérification idempotents.
• Ajout de la révocation d’une revendication sans suppression implicite des enregistrements.
• Ajout des filtres « vérifiées », « en attente » et « toutes » à la liste des zones.

v1.0.0 — version initiale

• Ajout de l’authentification par jeton Bearer et de l’isolation des zones entre utilisateurs.
• Ajout des portées de lecture et d’écriture.
• Ajout des points de terminaison de compte, de liste des zones et de gestion des enregistrements.
• Ajout d’une enveloppe de réponse cohérente comprenant un identifiant de requête.