Domaines personnalisés

Par défaut, vos liens de partage, de réception et de coffre sont servis sur un sous-domaine Coffrify. Un domaine personnalisé vous permet de les servir depuis votre propre nom, par exemple files.acme.com, afin que vos destinataires restent dans votre univers de marque de bout en bout. Cette page décrit le cycle de vie complet via l'API REST v1 : enregistrer un domaine, récupérer les enregistrements DNS à poser, déclencher la vérification de propriété, puis suivre l'état grâce aux évènements webhook. Toutes les opérations partagent un seul scope, domains:manage, et s'appliquent au workspace de la clé.

Le parcours en trois étapes

Servir vos liens sous votre domaine se fait toujours dans le même ordre. (1) Vous enregistrez le domaine avec POST /v1/domains : Coffrify vous renvoie une cible CNAME (cname_target) et un jeton de vérification (verification_token). (2) Vous posez deux enregistrements dans votre zone DNS : un CNAME qui pointe votre hôte vers cname_target, et un TXT qui prouve que vous contrôlez bien le domaine. (3) Vous appelez POST /v1/domains/{id}/verify : Coffrify résout votre DNS, et si tout correspond, bascule le domaine en verified: true. Le certificat HTTPS est provisionné automatiquement après la vérification, vous n'avez rien à gérer côté TLS.

1. Enregistrer un domaine

Le corps attend un unique champ domain, qui doit être un nom de domaine pleinement qualifié (FQDN). La valeur est normalisée en minuscules. Un domaine déjà enregistré pour le même workspace renvoie une erreur 409. Comme il s'agit d'une écriture, fournissez un en-tête Idempotency-Key pour pouvoir rejouer la requête sans créer de doublon.

import { Coffrify } from '@coffrify/sdk';
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
const domain = await coffrify.domains.create('files.acme.com');
 
console.log(domain.id);                 // dom_…
console.log(domain.cname_target);       // cible à poser dans votre CNAME
console.log(domain.verification_token); // valeur à poser dans votre TXT
console.log(domain.verified);           // false tant que le DNS n'est pas vérifié

Réponse 201 Created. Conservez id (vous en aurez besoin pour vérifier et supprimer) ainsi que cname_target et verification_token, qui sont les deux valeurs à reporter dans votre DNS.

{
  "id": "dom_8f2a1c",
  "domain": "files.acme.com",
  "cname_target": "edge.coffrify.com",
  "verified": false,
  "verification_token": "cof-verify-7Qx2kP9mLr4nDw",
  "created_at": "2026-06-10T09:14:00Z"
}

2. Poser les enregistrements DNS

Vous devez créer deux enregistrements dans la zone du domaine. Le CNAME route le trafic vers l'infrastructure Coffrify ; le TXT préfixé _coffrify-verify prouve la propriété. Tant que les deux ne sont pas en place et propagés, la vérification échoue.

Pour éviter toute erreur de recopie, l'API peut vous fournir les enregistrements déjà calculés pour votre domaine, avec en plus un guide pas-à-pas par registrar. Appelez GET /v1/domains/{id}/dns-instructions : le tableau records contient les lignes exactes à poser (type, name, target, ttl), et registrar_guides détaille les étapes pour Cloudflare, OVH, Hostinger, Gandi, Namecheap, Google Domains et AWS Route 53.

$ curl https://api.coffrify.com/v1/domains/dom_8f2a1c/dns-instructions \
    -H "Authorization: Bearer $COFFRIFY_API_KEY"

{
  "domain": "files.acme.com",
  "verified": false,
  "records": [
    {
      "type": "CNAME",
      "name": "files",
      "target": "edge.coffrify.com",
      "ttl": 3600,
      "purpose": "Route the custom domain to Coffrify's edge."
    },
    {
      "type": "TXT",
      "name": "_coffrify-verify.files",
      "target": "cof-verify-7Qx2kP9mLr4nDw",
      "ttl": 3600,
      "purpose": "Prove domain ownership before activation."
    }
  ]
}

3. Vérifier la propriété

Une fois les enregistrements posés, déclenchez la vérification. Coffrify résout votre CNAME en direct et le compare à la cible attendue. Si la valeur correspond, le domaine passe verified: true. La réponse contient just_verified, vrai uniquement lors de la première bascule réussie, et observed_cname, la liste des valeurs CNAME effectivement vues, utile pour diagnostiquer un enregistrement mal recopié.

const result = await coffrify.domains.verify('dom_8f2a1c');
 
if (result.verified) {
  console.log('Domaine actif, liens servis sous', result.domain);
} else {
  // DNS pas encore propagé ou CNAME erroné
  console.log('Attendu :', result.cname_target);
  console.log('Observé :', result.observed_cname); // []  ou autre valeur
}

{
  "id": "dom_8f2a1c",
  "domain": "files.acme.com",
  "cname_target": "edge.coffrify.com",
  "verified": true,
  "just_verified": true,
  "observed_cname": ["edge.coffrify.com"]
}

Si verified reste false, c'est presque toujours que le DNS n'a pas fini de se propager ou que le CNAME ne pointe pas vers la valeur exacte de cname_target. Comparez observed_cname à cname_target, corrigez l'enregistrement si besoin, attendez quelques minutes puis rappelez le même endpoint. La vérification est rejouable autant de fois que nécessaire.

Lister et inspecter vos domaines

GET /v1/domains renvoie tous les domaines du workspace, vérifiés comme en attente, sous la forme d'une liste (object: "list"). GET /v1/domains/{id} renvoie un domaine précis avec son état de vérification courant.

const { data } = await coffrify.domains.list();
 
for (const d of data) {
  console.log(d.domain, d.verified ? 'vérifié' : 'en attente');
}
 
const one = await coffrify.domains.get('dom_8f2a1c');
console.log(one.verified_at); // date de vérification, ou null

Supprimer un domaine

La suppression détache le domaine et arrête le renouvellement de son certificat. Vos liens repassent alors sur le sous-domaine Coffrify par défaut. Pensez à retirer les enregistrements CNAME et TXT de votre zone DNS une fois la suppression effectuée.

$ curl -X DELETE https://api.coffrify.com/v1/domains/dom_8f2a1c \
    -H "Authorization: Bearer $COFFRIFY_API_KEY"
{ "id": "dom_8f2a1c", "object": "domain", "deleted": true }

Évènements webhook

Plutôt que d'interroger la vérification en boucle, abonnez un webhook à ces évènements pour réagir automatiquement au cycle de vie d'un domaine. domain.verification_failed est particulièrement utile pour alerter quand un DNS posé ne correspond pas à la cible attendue.

Erreurs courantes