Seguridad y claves de API

Tipos de clave

Permiso	Puede hacer	Úsala para
full_access	Todos los endpoints	Tus propias herramientas, la CLI, el servidor MCP, scripts de administración
sending_access	Solo POST /emails y POST /emails/batch	Servidores de aplicaciones que solo envían correo

Llamar a cualquier otro endpoint con una clave sending_access devuelve 401 restricted_api_key (“This API key is restricted to only send emails”).

Claves restringidas a un dominio

Una clave sending_access puede vincularse además a un dominio con domain_id. Entonces solo puede enviar desde direcciones de ese dominio; cualquier otro from devuelve 401 restricted_api_key. Úsala para dar a cada producto o cliente su propia clave.

Node.js

api-keys.ts

import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost();

// A key that can only send, and only from one domain.
const { data: key, error } = await spacepost.apiKeys.create({
  name: "worker-prod",
  permission: "sending_access",
  domainId: "0192e1c4-0000-7000-8000-000000000001",
});
if (error) throw new Error(error.message);
console.log(key.token); // sp_live_..., shown only once

const { data: keys } = await spacepost.apiKeys.list();
console.log(keys?.data.map((k) => `${k.name} ${k.prefix}... ${k.permission}`));

await spacepost.apiKeys.remove(key.id);

cURL

curl -X POST https://api.spacepost.dev/api-keys \
  -H "Authorization: Bearer $SPACEPOST_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "worker-prod", "permission": "sending_access", "domain_id": "0192e1c4-0000-7000-8000-000000000001" }'

Response (the token is shown only once)

{ "id": "0192e1c4-0000-7000-8000-0000000000e1", "token": "sp_live_Ab12Cd34Ef56Gh78Ij90Kl12Mn34Op56" }

name tiene de 1 a 50 caracteres. domain_id solo se permite con sending_access.

Cómo se guardan las claves

• Las claves tienen la forma sp_live_ seguida de 32 caracteres base62 aleatorios.
• SpacePost guarda solo un hash SHA-256. La clave completa se muestra una vez, al crearla. Si la pierdes, crea una nueva.
• El panel y GET /api-keys muestran el prefijo (sp_live_ más 4 caracteres), el permiso, el dominio y last_used_at.
• Eliminar una clave (DELETE /api-keys/{id}) la revoca de inmediato.

Buenos hábitos

• Nunca pongas claves en código de cliente, apps móviles ni repositorios públicos. La API permite peticiones entre orígenes solo para que funcionen los playgrounds de API; envía el correo desde tu servidor.
• Usa una clave por servicio y entorno, con un nombre claro (worker-prod, ci-staging).
• Prefiere sending_access, restringida a un dominio.
• Rota creando una clave nueva, desplegándola, comprobando el last_used_at de la antigua y eliminando después la antigua.
• Guarda las claves en un gestor de secretos o en variables de entorno, no en el código.
• Revoca de inmediato una clave que se filtre. Si se subió a GitHub, da por hecho que está comprometida.
• SMTP usa la misma clave como contraseña. Consulta Relé SMTP.

Los secretos de los webhooks son aparte

Cada webhook tiene su propio signing_secret. Consulta Verificar firmas.

Transporte

Todo el tráfico usa TLS. La API se sirve en https://api.spacepost.dev, y el relé SMTP en smtp.spacepost.dev:25976 exige STARTTLS antes de la autenticación (todavía no se ofrece TLS implícito en el puerto 465).

Otras protecciones: los intentos fallidos de autenticación SMTP se limitan por IP; los endpoints de webhooks y las URL de los archivos adjuntos deben resolver a direcciones públicas (se rechazan las redes privadas); los enlaces de baja se firman por contacto.

Dónde se guardan tus datos

SpacePost lo opera Studio 404 d.o.o., una empresa de la UE con sede en Eslovenia, y guarda los datos de los clientes en la UE:

• Envío: Amazon SES en AWS eu-central-1 (Fráncfort, Alemania). Todos los dominios envían desde esta región.
• Aplicación y base de datos: la API, el panel, los workers y la base de datos Postgres se ejecutan en Railway, en su región de la UE (Ámsterdam, Países Bajos).
• Aislamiento: cada equipo envía a través de su propio tenant de SES, así que los problemas de reputación de un cliente no afectan a los demás.
• El sitio web y la documentación son páginas estáticas servidas por la red global de Cloudflare; ahí no se guardan datos de clientes.

Algunos proveedores (AWS, Stripe, Railway) son empresas de EE. UU. Aparecen, con lo que procesan y dónde, en la lista de subencargados (disponible en inglés). Un anexo de tratamiento de datos conforme al RGPD forma parte de los Términos del servicio, que se rigen por la ley eslovena (disponibles en inglés).

Notificar una vulnerabilidad

Escribe a support@spacepost.dev con los detalles. Por favor, no hagas pruebas con datos de otros clientes.