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 |
mssp.read | Listar clientes MSSP (solo partner_admin) |
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 | Quota mensual excedida | Upgradear tier o addon |
| 429 | Rate limit | Ver Rate limits |
| 503 | Feature no disponible en el tier | Upgradear tier |
MSSP — impersonación
En rol partner_admin, para hacer requests en nombre de un cliente:
GET /v1/domains
Authorization: Bearer <partner_api_key>
X-Impersonate-Tenant: <client_tenant_uuid>La API valida que el client_tenant pertenece al partner y ejecuta la query con RLS del cliente. Auditado como MSSP_IMPERSONATE.
Corporativo — cross-tenant
En rol corporativo_admin, algunos endpoints permiten ?tenant_id=<subsidiary> como query param sin necesidad de impersonar. La visibilidad cross-tenant es directa (a diferencia de partner).
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.