Sicherheit und API-Schlüssel

Schlüsseltypen

Berechtigung	Darf	Verwendung für
full_access	Jeden Endpoint	Dein eigenes Tooling, CLI, MCP-Server, Admin-Skripte
sending_access	Nur POST /emails und POST /emails/batch	Anwendungsserver, die nur E-Mails senden

Wenn du mit einem sending_access-Schlüssel einen anderen Endpoint aufrufst, erhältst du 401 restricted_api_key (“This API key is restricted to only send emails”).

Auf Domains beschränkte Schlüssel

Ein sending_access-Schlüssel kann zusätzlich mit domain_id an eine Domain gebunden werden. Er kann dann nur von Adressen dieser Domain senden; jedes andere from liefert 401 restricted_api_key. Nutze das, um jedem Produkt oder Kunden einen eigenen Schlüssel zu geben.

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 ist 1 bis 50 Zeichen lang. domain_id ist nur mit sending_access erlaubt.

Wie Schlüssel gespeichert werden

• Schlüssel sehen aus wie sp_live_, gefolgt von 32 zufälligen Base62-Zeichen.
• SpacePost speichert nur einen SHA-256-Hash. Der vollständige Schlüssel wird einmal angezeigt, bei der Erstellung. Wenn du ihn verlierst, erstelle einen neuen.
• Das Dashboard und GET /api-keys zeigen das Präfix (sp_live_ plus 4 Zeichen), die Berechtigung, die Domain und last_used_at.
• Das Löschen eines Schlüssels (DELETE /api-keys/{id}) widerruft ihn sofort.

Gute Gewohnheiten

• Lege Schlüssel nie in clientseitigem Code, in Mobile-Apps oder öffentlichen Repositories ab. Die API erlaubt Cross-Origin-Anfragen nur, damit API-Playgrounds funktionieren; sende E-Mails von deinem Server.
• Verwende pro Dienst und Umgebung einen Schlüssel mit eindeutigem Namen (worker-prod, ci-staging).
• Bevorzuge sending_access, auf eine Domain beschränkt.
• Rotiere, indem du einen neuen Schlüssel erstellst, ihn ausrollst, last_used_at des alten prüfst und den alten dann löschst.
• Bewahre Schlüssel in einem Secret Manager oder in Umgebungsvariablen auf, nicht im Code.
• Widerrufe einen Schlüssel sofort, wenn er geleakt wird. Wurde er auf GitHub committet, gehe davon aus, dass er kompromittiert ist.
• SMTP verwendet denselben Schlüssel als Passwort. Siehe SMTP-Relay.

Webhook-Secrets sind getrennt

Jeder Webhook hat sein eigenes signing_secret. Siehe Signaturen prüfen.

Transport

Der gesamte Datenverkehr nutzt TLS. Die API wird unter https://api.spacepost.dev bereitgestellt, und das SMTP-Relay unter smtp.spacepost.dev:25976 verlangt STARTTLS vor der Authentifizierung (implizites TLS auf Port 465 wird noch nicht angeboten).

Weitere Schutzmaßnahmen: Fehlgeschlagene SMTP-Authentifizierungsversuche werden pro IP gedrosselt; Webhook-Endpoints und Anhang-URLs müssen auf öffentliche Adressen auflösen (private Netzwerke werden abgelehnt); die Abmeldelinks sind pro Kontakt signiert.

Wo deine Daten gespeichert werden

SpacePost wird von Studio 404 d.o.o. betrieben, einem EU-Unternehmen in Slowenien, und speichert Kundendaten in der EU:

• Versand: Amazon SES in AWS eu-central-1 (Frankfurt, Deutschland). Jede Domain sendet aus dieser Region.
• Anwendung und Datenbank: API, Dashboard, Worker und die Postgres-Datenbank laufen bei Railway in dessen EU-Region (Amsterdam, Niederlande).
• Isolation: Jedes Team sendet über einen eigenen SES-Tenant, sodass Reputationsprobleme eines Kunden andere nicht beeinträchtigen.
• Website und Docs sind statische Seiten, die über das globale Netzwerk von Cloudflare ausgeliefert werden; dort werden keine Kundendaten gespeichert.

Einige Anbieter (AWS, Stripe, Railway) sind US-Unternehmen. Sie sind mit dem, was sie verarbeiten und wo, in der Liste der Unterauftragsverarbeiter aufgeführt (auf Englisch). Ein DSGVO-Auftragsverarbeitungsvertrag ist Teil der Nutzungsbedingungen, die slowenischem Recht unterliegen.

Eine Sicherheitslücke melden

Schreib eine E-Mail mit Details an support@spacepost.dev. Bitte teste nicht mit Daten anderer Kunden.