Autenticare le tue chiamate alla API pubblica

La API pubblica CaptainDNS si autentica tramite una chiave inviata nell'header HTTP Authorization. Niente OAuth, niente sessione, niente cookie. Questa guida copre il formato delle chiavi, il loro ciclo di vita è le buone pratiche di archiviazione.

Invio della chiave

POST /public/v1/resolve HTTP/1.1
Host: api.captaindns.com
Authorization: Bearer cdns_live_a3f2XK7mN9QrVtZ4yP1sH6eL8cF2dB5aR3gW7kJxM
Content-Type: application/json

{"qname":"captaindns.com","qtype":"A"}

Lo schema è sempre Bearer. Qualsiasi altro schema produce 401 INVALID_API_KEY. Le chiavi distinguono maiuscole è minuscole.

Formato delle chiavi

Una chiave ha tre segmenti:

cdns_<ambiente>_<36 caratteri alfanumerici minuscoli>

Il prefisso mostrato nella dashboard e cdns_<env>_ seguito da 8 caratteri. Il segreto completo non viene mai memorizzato nel database; CaptainDNS conserva solo il suo HMAC-SHA256 con pepper.

Ambienti

Le chiavi cdns_test_* sono tecnicamente identiche a quelle cdns_live_*: stessi endpoint, stessi scope, stesso consumo di crediti. Esistono per distinguere nei log il traffico di sviluppo da quello di produzione. Raccomandiamo una chiave per ambiente (dev, staging, CI).

Scope

Ogni chiave porta uno o più scope. La guida agli scope li elenca tutti; in sintesi:

• dns:read: risoluzione DNS, propagazione, DNSSEC, WHOIS IP.
• mail:read: SPF, DKIM, DMARC, BIMI, MTA-STS, TLS-RPT, DANE, blacklist, SMTP, audit di header email.
• mail:write: deliverability score (unico endpoint attualmente dietro questo scope).
• web:read: verifiche URL, crawl di pagine, rilevamento phishing.

Una chiamata a un endpoint il cui scope non è presente sulla chiave restituisce 403 INSUFFICIENT_SCOPE.

Rotazione senza interruzione

Una chiave compromessa o obsoleta non si sostituisce a caldo. Il flusso supportato è la rotazione:

1. Dalla dashboard o tramite the CaptainDNS dashboard, attivi la rotazione.
2. CaptainDNS genera una nuova chiave con gli stessi scope, limiti è ambiente.
3. La chiave vecchia rimane valida 7 giorni. In questo periodo i tuoi servizi possono migrare progressivamente.
4. Allo scadere della grace period, la vecchia chiave viene revocata automaticamente.

Aggiorna il tuo gestore di segreti prima della fine della grace period. Oltre tale termine, ogni richiesta con la vecchia chiave restituisce 401 REVOKED_API_KEY.

Revoca immediata

Se una chiave perde in pubblico (repository Git, log, collega che lascia), due opzioni:

• Dalla dashboard: pulsante Revoca sulla chiave, conferma. Effetto immediato, nessuna grace period.
• Tramite the CaptainDNS dashboard: stesso effetto, utile per automatizzare da CI.

Le richieste in corso al momento della revoca vengono completate; quelle successive restituiscono 401 REVOKED_API_KEY.

Allowlist IP

I piani Business ed Enterprise possono limitare una chiave a una lista di CIDR. La verifica è applicata a monte dell'handler, quindi zero crediti consumati se l'IP non è autorizzato. La risposta e 403 IP_NOT_ALLOWED, con l'IP rilevato in details.

Esempio di chiave limitata ai runner GitHub Actions è al backend di produzione:

{
  "ip_allowlist": [
    "4.175.114.0/23",
    "52.237.144.10/32"
  ]
}

Aggiornare la lista non richiede rotazione: modifica la chiave dalla dashboard è la nuova lista ha effetto entro un minuto.

Buone pratiche di archiviazione

• Gestore di segreti: 1Password, Doppler, AWS Secrets Manager, Vault. Mai in un file .env committato o in uno YAML CI inline.
• Variabile d'ambiente a runtime: inietta la chiave come variabile d'ambiente all'avvio del processo.
• Rotazione periodica: 90 giorni per i carichi critici, 180 giorni altrimenti.
• Niente condivisione tra team: una chiave per servizio, non una chiave master condivisa da tutto l'SRE.
• Scope minimi: se la tua integrazione fa solo DMARC check, non concedere web:read ne mail:write.

Rilevamento delle fughe

CaptainDNS è iscritto al programma di rilevamento segreti di GitHub. Se pubblichi per errore una chiave live in un repository pubblico, il pattern cdns_live_* viene rilevato è l'owner riceve una notifica. La chiave viene revocata automaticamente. Riceverai un'email con lo SHA del commit in causa è i passi successivi.

Risoluzione dei problemi di autenticazione

• 401 INVALID_API_KEY: prefisso assente o errato, chiave assente dopo Bearer, segreto alterato.
• 401 REVOKED_API_KEY: chiave revocata manualmente o automaticamente. Genera una nuova.
• 401 EXPIRED_API_KEY: hai impostato expires_at alla creazione, la data è passata. Crea una nuova chiave.
• 403 IP_NOT_ALLOWED: l'IP sorgente non è in allowlist. Verifica anche che X-Forwarded-For sia propagato correttamente.
• 500 INTERNAL_ERROR: indica un problema lato CaptainDNS; apri un ticket di supporto con il request_id.

Passa poi alla guida agli scope per scegliere i permessi adatti, o al rate limiting se prepari un client ad alta frequenza.