API y claves

Claves de API

Una clave representa a una integración, no a una persona. Creá una por sistema y ambiente para poder revocarla sin afectar a otros consumidores.

1. Abrí Configuración → Claves de API.
2. Creá una clave con nombre descriptivo.
3. Elegí únicamente los scopes necesarios.
4. Copiala y almacenala en un gestor seguro.
5. Probá una operación de lectura antes de habilitar escrituras.
6. Registrá responsable, ambiente y fecha de rotación.

El valor secreto puede mostrarse una sola vez. No lo guardes en documentos, frontend, chats ni repositorios.

Scopes

Separá lectura, escritura y ejecución. Una integración que crea contactos no necesita administrar roles ni campañas. Para contexto sensible, respetá tenant y alcance CRM.

Para registrar acciones externas sobre un contacto, consultá la guía independiente de Eventos de contacto.

Webhooks y HTTP

• Usá HTTPS.
• Validá autenticidad o firma cuando esté disponible.
• Definí timeout y reintentos.
• No incluyas secretos en URL.
• Registrá identificadores y estado, no datos personales completos.
• Diseñá el receptor para solicitudes repetidas.

Rotación o revocación

Creá la nueva clave, actualizá el consumidor, verificá tráfico y recién entonces revocá la anterior. Ante exposición, revocá de inmediato y revisá acciones realizadas con esa credencial.

Checklist de producción

• Clave por ambiente e integración.
• Scopes mínimos.
• Secretos fuera del código.
• Payload validado.
• Idempotencia definida.
• Retries acotados.
• Errores observables.
• Responsable y rotación documentados.