Autenticación de API
La plataforma expone una REST API v1 en https://platform.emate.cloud/v1 con OpenAPI/Swagger en /docs. Cubre CRUD de dominios, query de reportes, alerts, phishing intake, threat intel, SSPM, MSSP y audit log.
Modelos de autenticación
- API keys — machine-to-machine con scopes granulares. Recomendado para automation.
- Session cookies — usadas por el dashboard. No documentado ni soportado para uso programático.
Crear una API key
En Settings → API Keys → New Key:
- Nombre — descriptivo (
ci-pipeline,terraform,siem-forwarder). - Scopes — checklist granular. Elegir solo los necesarios.
- Expiración — opcional. Recomendado 90 días con rotación automática.
- IP allowlist — opcional. Solo IPs específicas pueden usar la key.
Al guardar, la key aparece una sola vez. Guardala en tu secret manager. Si la perdés, hay que rotar (crear una nueva y revocar la vieja).
Scopes disponibles
Nomenclatura: dominio.acción.
| Scope | Qué permite |
|---|---|
domains.read | Listar dominios y sus scores |
domains.write | Crear, editar, borrar dominios |
reports.read | Query de reportes DMARC/RUF |
alerts.read | Listar alerts |
alerts.write | Ack, resolve, silence alerts |
phishing.report | Ingest de phishing (usado por Gmail add-on) |
phishing.read | Query de reportes de phishing |
phishing.write | Actualizar status, detonar URLs |
threats.read | Query del feed de IOCs |
sspm.read | Listar findings SSPM |
sspm.write | Remediar findings |
audit.read | Query del audit log |
webhooks.write | Configurar webhooks salientes |
Podés combinar múltiples scopes en una key.
Uso de la key
curl -H "Authorization: Bearer $API_KEY" \
https://platform.emate.cloud/v1/domainsHeader obligatorio: Authorization: Bearer <key>.
Errores comunes
| Código | Significado | Solución |
|---|---|---|
| 401 | Key inválida o expirada | Verificá el header, la key y la expiración |
| 403 | Key válida pero sin el scope necesario | Rotar key con scopes ampliados |
| 402 | Límite de uso contratado alcanzado | Revisar consumo o ampliar la licencia |
| 429 | Rate limit | Ver Rate limits |
| 503 | Capacidad no disponible en la licencia | Revisar la licencia contratada |
Acceso multi-organización
Las integraciones para partners, MSSP y organizaciones corporativas requieren una modalidad contratada y autorización expresa. Los endpoints, permisos y procedimientos aplicables se entregan en la documentación privada de onboarding correspondiente.
Rotación
Buenas prácticas:
- Nunca hardcodees keys en repos.
- Usá secret manager (AWS Secrets Manager, Vault, 1Password) para inyectar keys en runtime.
- Rotá cada 90 días como máximo.
- Al rotar: crear la nueva → deployear con la nueva → verificar → revocar la vieja.