Sicurezza e chiavi API

Tipi di chiave

Permesso	Che cosa può fare	Da usare per
full_access	Ogni endpoint	I tuoi strumenti, la CLI, il server MCP, gli script di amministrazione
sending_access	Solo POST /emails e POST /emails/batch	Server applicativi che si limitano a inviare email

Chiamare qualsiasi altro endpoint con una chiave sending_access restituisce 401 restricted_api_key (“This API key is restricted to only send emails”).

Chiavi limitate a un dominio

Una chiave sending_access può inoltre essere vincolata a un dominio con domain_id. Potrà quindi inviare solo da indirizzi di quel dominio; qualsiasi altro from restituisce 401 restricted_api_key. Usala per dare a ogni prodotto o cliente la propria chiave.

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 è lungo da 1 a 50 caratteri. domain_id è consentito solo con sending_access.

Come vengono conservate le chiavi

• Le chiavi hanno la forma sp_live_ seguito da 32 caratteri base62 casuali.
• SpacePost conserva solo un hash SHA-256. La chiave completa viene mostrata una sola volta, alla creazione. Se la perdi, crea una nuova chiave.
• La dashboard e GET /api-keys mostrano il prefisso (sp_live_ più 4 caratteri), il permesso, il dominio e last_used_at.
• Eliminare una chiave (DELETE /api-keys/{id}) la revoca immediatamente.

Buone abitudini

• Non mettere mai le chiavi nel codice lato client, nelle app mobili o nei repository pubblici. L’API consente le richieste cross-origin solo perché funzionino i playground delle API; invia le email dal tuo server.
• Usa una chiave per ogni servizio e ambiente, con un nome chiaro (worker-prod, ci-staging).
• Preferisci sending_access, limitata a un dominio.
• Ruota creando una nuova chiave, distribuendola, controllando last_used_at di quella vecchia e poi eliminando la vecchia.
• Conserva le chiavi in un gestore di secret o in variabili d’ambiente, non nel codice.
• Revoca subito se una chiave trapela. Se è stata committata su GitHub, considerala compromessa.
• SMTP usa la stessa chiave come password. Vedi Relay SMTP.

I secret dei webhook sono separati

Ogni webhook ha il proprio signing_secret. Vedi Verificare le firme.

Trasporto

Tutto il traffico usa TLS. L’API è servita su https://api.spacepost.dev e il relay SMTP su smtp.spacepost.dev:25976 richiede STARTTLS prima dell’autenticazione (il TLS implicito sulla porta 465 non è ancora disponibile).

Altre protezioni: i tentativi di autenticazione SMTP falliti sono limitati per IP; gli endpoint dei webhook e gli URL degli allegati devono risolvere a indirizzi pubblici (le reti private vengono rifiutate); i link di annullamento dell’iscrizione sono firmati per ogni contatto.

Dove sono conservati i tuoi dati

SpacePost è gestito da Studio 404 d.o.o., un’azienda UE con sede in Slovenia, e conserva i dati dei clienti nell’UE:

• Invio: Amazon SES nella regione AWS eu-central-1 (Francoforte, Germania). Ogni dominio invia da questa regione.
• Applicazione e database: API, dashboard, worker e database Postgres girano su Railway nella sua regione UE (Amsterdam, Paesi Bassi).
• Isolamento: ogni team invia tramite il proprio tenant SES, quindi i problemi di reputazione di un cliente non influiscono sugli altri.
• Sito web e documentazione sono pagine statiche servite dalla rete globale di Cloudflare; lì non viene conservato alcun dato dei clienti.

Alcuni fornitori (AWS, Stripe, Railway) sono aziende statunitensi. Sono elencati, con ciò che trattano e dove, nell’elenco dei sub-responsabili (disponibile in inglese). Un accordo sul trattamento dei dati conforme al GDPR fa parte dei Termini di servizio, regolati dalla legge slovena.

Segnalare una vulnerabilità

Scrivi a support@spacepost.dev con i dettagli. Ti chiediamo di non fare test sui dati di altri clienti.