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 |
Nota: los 15 endpoints de la familia text/* (encoding base64, conversion JSON/YAML, hash, slug, regex, password, etc.) también estan asociados al scope dns:read para simplificar la atribucion. No efectuan ninguna resolución DNS. Consulta la referencia OpenAPI para la lista completa.
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.