Elegir los scopes adecuados para tu integración
Los scopes restringen lo que una clave puede hacer. Una clave lleva uno o mas scopes; una llamada a un endpoint cuyo scope no esta 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 | Proposito | Uso tipico |
|---|---|---|
dns:read | Lectura de datos DNS | Watcher DNS, scripts CI, troubleshooting |
mail:read | Diagnosticos de autenticación de correo | Auditoria SPF/DKIM/DMARC, monitoring |
mail:write | Operaciones costosas de scoring de correo | Deliverability score en pipeline |
web:read | Analisis de página y URL | Detección de phishing, verificación de enlaces |
Ningun scope implica otro. mail:write no hereda de mail:read.
Mapeo completo de endpoints
dns:read
| Endpoint | Créditos | Descripcion |
|---|---|---|
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 |
mail:read
| Endpoint | Créditos | Descripcion |
|---|---|---|
POST /public/v1/spf/lookup | 1 | Lookup y parsing SPF |
POST /public/v1/dkim/lookup | 1 | Lookup DKIM por selector |
POST /public/v1/dmarc/lookup | 1 | Lookup y parsing DMARC |
POST /public/v1/bimi/lookup | 2 | Lookup BIMI con recuperacion del logo |
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 | Analisis de cabecera bruta |
mail:write
| Endpoint | Créditos | Descripcion |
|---|---|---|
POST /public/v1/deliverability/score | 30 | Score agregado de DMARC, BIMI y reputacion |
El scope mail:write aisla el endpoint mas caro. Se recomienda una clave dedicada si tu integración lo usa.
web:read
| Endpoint | Créditos | Descripcion |
|---|---|---|
POST /public/v1/url/check | 3 | Analisis de cadena de redirecciones |
POST /public/v1/page/crawl-check | 10 | Crawl de página con extraccion de meta |
POST /public/v1/phishing/check | 8 | Detección heuristica de phishing |
Estrategias de asignacion
Una unica clave con todos los scopes (fragil, no recomendado): practica para prototipar, peligrosa en producción.
Una clave por servicio (recomendado): cada microservicio o script tiene su propia clave con los scopes necesarios.
Una clave por entorno: dev, staging y prod tienen sus propias claves, distinguidas por prefijo y nombre en el dashboard.
Clave con scope unico para mail:write: separar el deliverability score evita que un bucle involuntario agote tu cupo.
Anadir o quitar un scope
Los scopes se fijan en la creacion. Para modificar los de una clave existente:
- Crea una nueva clave con los scopes deseados.
- Desplegala 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.