Référence de l'API
Tout ce que fait la console passe par une API HTTP que vous pouvez appeler vous-même : depuis un cron, un script de déploiement ou un outil interne. Cette page couvre le modèle d'autorisation, tous les endpoints, l'émission d'un certificat, la métadonnée métier, la vérification d'un sous-domaine et la description OpenAPI.
Modèle d'autorisation
api_key ──< grant >── domain
│
└── scopes[]| Scope | Autorise |
|---|---|
cert:read | Lire les certificats et leurs événements |
cert:issue | Émettre |
cert:renew | Renouveler |
cert:revoke | Révoquer / supprimer |
cert:export | Télécharger la clé privée (en plus de read) |
dns:read | Lister les enregistrements de la zone |
dns:write | UPSERT / DELETE d'enregistrements |
admin:* | Tout, sur tous les domaines, + console |
Une clé sans grant ne peut rien faire. Les droits sont par domaine : la clé du NAS ne peut pas émettre pour le domaine du serveur de build. Les clés se gèrent dans Clés & droits.
Deux mécanismes distincts
| Console web | API | |
|---|---|---|
| Identifiant | email + mot de passe | clé d'API |
| Stockage | argon2id | sha256 |
| Transport | cookie httpOnly / SameSite=lax | en-tête Authorization |
Le mot de passe protège un secret à faible entropie choisi par un humain : il lui faut un KDF lent. Une clé d'API porte 256 bits d'entropie CSPRNG — il n'y a rien à brute-forcer, sha256 suffit et reste rapide à chaque requête.
Un compte inexistant et un mauvais mot de passe consomment le même temps de calcul : impossible d'énumérer les comptes par la latence.
Format des clés
lc_<prefix8hex>_<secret base64url 32 octets>Le préfixe est indexé et affichable. Une clé fournie par l'opérateur (ADMIN_API_KEY) peut être une chaîne opaque quelconque : son préfixe de recherche dérive de son propre sha256, les deux formes partagent le même index.
Deux façons de s'authentifier
# 1. clé d'API directement (pratique pour cron/curl)
curl -H "Authorization: Bearer lc_..." https://certs.example.com/api/v1/certificates
# 2. échange contre un JWT court (1 h), scopes embarqués dans le token
TOKEN=$(curl -s -X POST https://certs.example.com/api/v1/auth/token \
-H "Authorization: Bearer lc_..." | jq -r .access_token)
curl -H "Authorization: Bearer $TOKEN" https://certs.example.com/api/v1/certificatesLa console d'admin utilise un cookie de session httpOnly + SameSite=lax portant un JWT équivalent, obtenu par email + mot de passe.
Endpoints
Authentification
GET /api/setup { setup_required: bool }
POST /api/setup création du compte admin (une seule fois)
POST /api/v1/auth/token clé d'API -> JWTCertificats
GET /api/v1/certificates ?status= &domain= &expires_within_days= &limit= &metadata.<clé>=
POST /api/v1/certificates 202 + Location
GET /api/v1/certificates/{id}
PATCH /api/v1/certificates/{id} met à jour la métadonnée
DELETE /api/v1/certificates/{id} ?purge=true pour effacer la ligne
POST /api/v1/certificates/{id}/renew
GET /api/v1/certificates/{id}/bundle ?format=json|pem &include=fullchain,cert,chain,key
GET /api/v1/certificates/{id}/events ?stream=1 pour du SSESous-domaines
GET /api/v1/subdomains/{fqdn} ce sous-domaine est-il déjà pris ?DNS
GET /api/v1/dns/records ?domain_id=
PUT /api/v1/dns/records
DELETE /api/v1/dns/records ?fqdn= &type= &values= &ttl=Divers
GET /api/v1/acme/account
GET /api/openapi.json description OpenAPI 3.1 (authentifiée)
GET /api/healthz
POST /api/mcp serveur MCP pour agents IALe serveur MCP est décrit dans Serveur MCP.
Administration (session console)
POST|GET|DELETE /api/admin/session email+mot de passe / whoami / logout
GET|POST /api/admin/providers ?force=true pour enregistrer malgré un test en échec
POST /api/admin/providers/probe teste des credentials sans les stocker
PATCH|DELETE /api/admin/providers/{id}
GET /api/admin/providers/{id}/zones zones hébergées visibles
GET /api/admin/providers/{id}/policy politique IAM complète (?zone_id= à ajouter)
GET|POST /api/admin/domains
POST /api/admin/domains/preflight les contrôles d'un ajout, sans rien écrire
DELETE /api/admin/domains/{id} ?force=true pour supprimer avec ses certificats
GET|POST /api/admin/keys
PATCH|DELETE /api/admin/keys/{id}
GET /api/admin/statsÉmettre un certificat
curl -X POST https://certs.example.com/api/v1/certificates \
-H "Authorization: Bearer $TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'content-type: application/json' \
-d '{
"domains": ["nas.home.example.com"],
"key_type": "ec-256",
"auto_renew": true,
"renew_before_days": 30,
"webhook_url": "https://nas.home.example.com/hooks/cert",
"dns": { "create_record": true, "target_ip": "192.168.1.50", "ttl": 60 }
}'La réponse est un 202 Accepted immédiat. Suivi :
curl -N -H "Authorization: Bearer $TOKEN" \
"https://certs.example.com/api/v1/certificates/$ID/events?stream=1"Machine à états :
pending → dns_propagating → validating → issued
↘ failed (retry exponentiel, 5 essais)
issued → revoked | expiredMétadonnée métier
Chaque sous-domaine porte une map clé/valeur de chaînes, fournie par le système appelant pour le rattacher à son contexte : tenant, environnement, ticket, identifiant interne.
curl -X POST …/api/v1/certificates -H "Authorization: Bearer $TOKEN" \
-d '{
"domains": ["nas.home.example.com"],
"metadata": { "tenant_id": "acme-corp", "env": "prod", "ticket": "OPS-1421" }
}'Mise à jour — merge par défaut, replace pour écraser :
curl -X PATCH …/api/v1/certificates/$ID \
-d '{ "metadata": { "tenant_id": "other-corp" }, "mode": "replace" }'Filtrage à la liste, une clé à la fois :
curl "…/api/v1/certificates?metadata.tenant_id=acme-corp"Le filtre est appliqué côté application, pas en SQL : les opérateurs JSON diffèrent entre SQLite et Postgres et la colonne n'est indexée dans aucun des deux, donc il n'y a rien à gagner à le pousser dans la requête.
Limites : 20 entrées, clé de 64 caractères dans [A-Za-z0-9._:-], valeur de 512 caractères, 4096 octets une fois sérialisé. C'est du contexte, pas un magasin de documents.
Vérifier si un sous-domaine est pris
curl …/api/v1/subdomains/nas.home.example.com -H "Authorization: Bearer $TOKEN"{
"fqdn": "nas.home.example.com",
"available": false,
"managed_domain": "home.example.com",
"dns": {
"exists": true,
"managed": true,
"records": [{ "type": "A", "ttl": 60, "values": ["192.168.1.50"] }]
},
"certificate": { "id": "cert_…", "status": "issued", "days_remaining": 89, "metadata": {} },
"metadata": { "tenant_id": "acme-corp" }
}Les deux sources de vérité sont interrogées séparément parce qu'elles peuvent diverger : un enregistrement peut exister dans la zone sans que local-cert le connaisse (créé à la main, ou par un autre outil), et un certificat peut exister ici sans que rien ne soit publié. available n'est vrai que si aucune des deux ne connaît le nom et que la zone était lisible — une zone illisible remonte dans dns.error plutôt que de faire passer le nom pour libre.
Nécessite cert:read sur le domaine couvrant. La moitié DNS n'est pas protégée davantage : c'est de la donnée publique, résolvable au dig par n'importe qui.
Documentation OpenAPI
La description OpenAPI 3.1 complète est servie sur GET /api/openapi.json (authentifiée — le schéma cartographie toute la surface d'un outil interne).
La console embarque un explorateur sur /admin/api : endpoints groupés par tag, filtre, paramètres et corps pré-remplis depuis le schéma, équivalent curl, et un bouton Envoyer qui exécute réellement la requête depuis le navigateur avec votre cookie de session.
Génération
Le document est généré, jamais écrit à la main :
| Élément | Source |
|---|---|
| Corps de requête | les schémas zod que les handlers valident (src/lib/validation.ts) |
| Réponses | src/lib/api/schemas.ts, reliées au runtime par z.infer |
| Opérations | src/lib/api/routes.ts |
Conversion via z.toJSONSchema() de zod 4. Les contraintes viennent donc gratuitement des validateurs — la regex de FQDN, les bornes de TTL, les longueurs de métadonnée apparaissent dans la spec parce qu'elles existent dans le code.
Trois garde-fous, exécutés par npm run openapi:check :
- Couverture — chaque handler App Router sur le disque doit figurer au registre, et réciproquement. Une route ajoutée sans documentation fait échouer le check.
- Cohérence input/output — aucun schéma de réponse ne doit diverger entre ses projections d'entrée et de sortie ; le générateur fait une passe unique, ce qui n'est correct que tant que c'est vrai (un
.default()ou un.transform()sur une réponse casserait l'hypothèse). - Résolution des
$ref— toute référence doit pointer sur un composant existant.
Le typage ferme la boucle : serializeCert retourne z.infer<typeof certificateSchema>, donc changer la forme sérialisée sans mettre à jour le schéma publié échoue à la compilation.
openapi:check ok — 30 operations over 19 paths, 36 component schemas, all $refs resolve.