Elegir los scopes adecuados para tu integración
Los scopes restringen lo que una clave puede hacer. Una clave lleva uno o más scopes; una llamada a un endpoint cuyo scope no está presente devuelve 403 INSUFFICIENT_SCOPE. Aplica el principio del menor privilegio: otorga a cada clave solo los scopes que su integración necesita.
Scopes disponibles
La V1 de la API pública expone cuatro scopes:
| Scope | Propósito | Uso típico |
|---|---|---|
dns:read | Lectura de datos DNS | Watcher DNS, scripts CI, troubleshooting |
mail:read | Diagnósticos de autenticación de correo | Auditoría SPF/DKIM/DMARC, monitorización de entregabilidad |
mail:write | Operaciones costosas de scoring de correo | Score de entregabilidad en un pipeline |
web:read | Análisis de página y URL | Detección de phishing, verificación de enlaces |
Ningún scope implica otro. mail:write no hereda de mail:read.
Mapeo completo de endpoints
dns:read
| Endpoint | Créditos | Descripción |
|---|---|---|
POST /public/v1/resolve | 1 | Resolución DNS estándar |
POST /public/v1/resolve/propagation | 3 | Test de propagación multi-resolver |
POST /public/v1/dnssec/check | 3 | Verificación de la cadena DNSSEC |
POST /public/v1/ip/whois | 2 | WHOIS de una IP |
POST /public/v1/ip/nslookup | 1 | DNS inverso (PTR) |
POST /public/v1/ip/netmask | 1 | Calculadora de máscara IPv4 |
POST /public/v1/rdap/lookup | 2 | RDAP/WHOIS de dominio |
POST /public/v1/domain/dns-check | 5 | Auditoría de servidores DNS |
mail:read
| Endpoint | Créditos | Descripción |
|---|---|---|
POST /public/v1/spf/lookup | 1 | Lookup y parsing SPF |
POST /public/v1/spf/validate | 1 | Validación SPF (sin lookup DNS) |
POST /public/v1/dkim/lookup | 1 | Lookup DKIM por selector |
POST /public/v1/dkim/validate | 1 | Validación DKIM (sin lookup DNS) |
POST /public/v1/dmarc/lookup | 1 | Lookup y parsing DMARC |
POST /public/v1/dmarc/validate | 1 | Validación DMARC (sin lookup DNS) |
POST /public/v1/bimi/lookup | 2 | Lookup BIMI con recuperación del logo |
POST /public/v1/bimi/validate | 2 | Validación BIMI (sin lookup DNS) |
POST /public/v1/bimi/logo/lookup | 2 | Descarga y validación del logo BIMI |
POST /public/v1/mta-sts/lookup | 2 | Lookup de la policy MTA-STS |
POST /public/v1/tls-rpt/lookup | 2 | Lookup TLS-RPT |
POST /public/v1/dane/lookup | 2 | Lookup DANE/TLSA para SMTP |
POST /public/v1/blacklist/ip | 5 | Blacklist check multi-RBL |
POST /public/v1/smtp/check | 6 | Test SMTP (HELO, STARTTLS, AUTH) |
POST /public/v1/mail/header-audit | 2 | Análisis de cabecera bruta |
POST /public/v1/mail/header-analyze | 2 | Análisis de cabeceras de correo |
POST /public/v1/mail/domain-check | 10 | Auditoría completa de dominio de correo |
POST /public/v1/dmarcbis/check | 2 | Análisis DMARCbis Tree Walk |
POST /public/v1/dmarc/report/analyze | 5 | Análisis de informe DMARC agregado |
POST /public/v1/certificats/bimi/parse | 1 | Parsing de certificado BIMI/VMC |
POST /public/v1/certificats/bimi/lookup | 2 | Descarga y parsing de certificado BIMI |
GET /public/v1/spf/hosted | 1 | Lista de los perfiles SPF alojados de la clave |
GET /public/v1/spf/hosted/{id} | 1 | Detalle de un perfil SPF alojado |
GET /public/v1/spf/hosted/{id}/history | 2 | Historial de resolución de un perfil (paginado) |
GET /public/v1/spf/hosted/{id}/stats | 2 | Estadísticas de un perfil (24 horas, 7 días, 30 días) |
mail:write
| Endpoint | Créditos | Descripción |
|---|---|---|
POST /public/v1/deliverability/score | 30 | Score agregado de DMARC, BIMI y reputación |
POST /public/v1/dmarc/generate | 1 | Generador de registro DMARC |
POST /public/v1/dmarcbis/migrate | 1 | Migración de DMARC a DMARCbis |
POST /public/v1/spf/hosted/{id}/resolve | 5 | Re-resolución forzada de un perfil SPF alojado |
El scope mail:write aísla los endpoints de escritura. Se recomienda una clave dedicada si tu integración usa el score de entregabilidad, para reducir el impacto en caso de fuga.
web:read
| Endpoint | Créditos | Descripción |
|---|---|---|
POST /public/v1/url/check | 3 | Análisis de cadena de redirecciones |
POST /public/v1/page/crawl-check | 10 | Crawl de página con extracción de meta |
POST /public/v1/phishing/check | 8 | Detección heurística de phishing |
POST /public/v1/http/headers-check | 2 | Cabeceras HTTP, cadena de redirecciones, TLS |
POST /public/v1/http/hsts-check | 3 | Análisis HSTS y elegibilidad para preload |
POST /public/v1/certificates/ssl/check | 2 | Certificado TLS de un servidor web y su cadena |
POST /public/v1/certificates/csr/parse | 2 | Análisis de conformidad de un CSR |
Transición de scope en /certificates/csr/parse. Este endpoint pertenecía a la familia mail:read y costaba 1 crédito. Como un CSR no tiene nada específicamente de mail, su scope objetivo ahora es web:read y su coste es de 2 créditos. Para no romper ninguna clave ya emitida, mail:read se sigue aceptando durante un período de transición, pero será retirado: crea tus nuevas claves con web:read y añade web:read a las claves existentes que llaman a este endpoint.
Nota: los 15 endpoints de la familia text/* (encoding base64, conversión JSON/YAML, hash, slug, regex, password, etc.) también están asociados al scope dns:read para simplificar la atribución. No efectúan ninguna resolución DNS. Consulta la referencia OpenAPI para la lista completa.
Estrategias de asignación
Una única clave con todos los scopes (frágil, no recomendado): le das a un solo secreto acceso a toda la API. Práctica para prototipar, peligrosa en producción. Pasa a una estrategia de varias claves en cuanto la integración se estabilice.
Una clave por servicio (recomendado): cada microservicio o script lleva su propia clave, con únicamente los scopes que necesita. Si un servicio filtra su clave, el incidente queda circunscrito a su perímetro.
Una clave por entorno: dev, staging y producción tienen cada uno su juego de claves, distinguidas por prefijo (cdns_test_* frente a cdns_live_*) y por nombre en el dashboard. Simplifica los paneles de consumo y las alertas.
Clave con scope único para mail:write: separar el score de entregabilidad (30 créditos) del resto evita que un bucle involuntario sobre ese único endpoint arruine tu cupo. Esa clave dedicada también puede llevar un rate limit aplicativo más estricto del lado cliente.
Añadir o quitar un scope
Los scopes se fijan en la creación. Para modificar los de una clave existente:
- Crea una nueva clave con los scopes deseados.
- Despliégala en tu gestor de secretos.
- Revoca la clave antigua.
Herramientas CaptainDNS relacionadas
Siguiente paso: entiende el modelo de créditos y luego lee el rate limiting.