Claves públicas y privadas

Cada organización tiene una clave pública y hasta 20 claves privadas activas. Las encontrarás en la página Seguridad, en las secciones Clave pública y Claves privadas. Los propietarios, administradores y desarrolladores pueden verlas; solo los propietarios y administradores pueden crearlas, revocarlas y rotarlas.

	Clave pública	Clave privada
Formato	`pk_…`	`sk_…`
¿Secreta?	No: se ve en el código fuente de tu página	Sí: como una contraseña
Dónde usarla	Navegadores, apps móviles, sitios estáticos	Servidores, funciones serverless, CI
Cómo se envía	`user_id` en el cuerpo o cabecera `X-Frontmail-Public-Key`	cabecera `Authorization: Bearer sk_…` o `accessToken` en el cuerpo
Comprobación de origen	✓ debe coincidir con los orígenes permitidos; sin `Origin` necesita Permitir apps móviles	una cabecera `Origin` se rechaza (`private_key_in_browser`) salvo que se permita
Turnstile	✓ cuando la plantilla lo exige	se omite
Límites de solicitudes	por organización, por IP, por clave	por organización, por clave
Endpoints	`send`, `send-form`, `uploads`, `messages/:id` (con token de estado)	todos, incluidos `send-batch`, `history`, `templates`

Clave pública

La clave pública solo identifica a tu organización. Cualquiera puede copiarla de tu sitio; por eso las solicitudes firmadas con ella se comprueban por origen, señales de bots y frecuencia, y por eso las plantillas no pueden usar destinatarios dinámicos salvo que lo permitas expresamente. Un cliente con clave pública solo puede leer el estado de sus propios mensajes, usando el status_token que devuelve send (enviado en la cabecera X-Frontmail-Status-Token).

Claves privadas

Las claves privadas se saltan las comprobaciones pensadas para el navegador, así que nunca deben llegar a uno. Usos típicos: enviar desde tu backend, el SDK de Node, envíos por lotes, leer el historial y npx frontmail types.

Crea una con Nueva clave privada. Se muestra una sola vez: cópiala y confirma con La he guardado en un lugar seguro. Frontmail solo guarda un hash y los cuatro últimos caracteres.
Ponle un nombre a cada clave (p. ej. «Backend de producción», «CI») para saber dónde se usa; la columna Último uso muestra cuándo se usó cada clave por última vez.
El interruptor Permitir la API con clave privada (Seguridad → Protección contra abusos) puede desactivar por completo el acceso con clave privada en la organización si solo envías desde navegadores; las solicitudes con clave privada fallan entonces con 403 forbidden.
Las solicitudes con clave privada que llevan cabecera Origin (es decir, que vienen de una página web) fallan con 403 private_key_in_browser. Esto también se aplica al campo accessToken del cuerpo al estilo de EmailJS y a los endpoints de lectura. Los servidores no envían Origin, así que el código de servidor no se ve afectado. Solo si de verdad necesitas una clave privada en un navegador (una herramienta de administración interna, nunca una página pública), activa Permitir claves privadas en navegadores (Seguridad → Protección contra abusos, desactivado por defecto).

Rotación

Claves privadas: crea una clave nueva, despliégala en tus servidores, comprueba que el Último uso de la clave antigua deja de cambiar y después haz clic en Revocar en la clave antigua. La revocación es inmediata; las solicitudes con una clave revocada fallan con invalid_private_key.

Clave pública: haz clic en Rotar clave en la sección Clave pública. Obtienes una clave nueva al instante; la antigua sigue funcionando durante un periodo de gracia de 24 horas para que puedas volver a desplegar tu sitio, y después falla con invalid_public_key. Rota la clave pública cuando veas abusos a pesar de los orígenes permitidos y Turnstile, o cuando traslades una app a otra organización.

La creación, revocación y rotación de claves quedan registradas en el registro de auditoría.