Authentifizierung

Jede Anfrage außer der Erreichbarkeitsprüfung trägt einen Schlüssel. Schlüssel weisen eine Organisation aus, nicht eine Person, und tragen deren Tarif und Kontingent.

Der Header

curl -sS "https://api.skautik.com/v1/api/properties?city=Berlin" \
  -H "X-API-Key: sk_live_9f21c4a70b8e…"

# Authorization: Bearer funktioniert ebenfalls, für Clients, denen das leichter fällt.
curl -sS "https://api.skautik.com/v1/api/properties?city=Berlin" \
  -H "Authorization: Bearer sk_live_9f21c4a70b8e…"

Beide Header funktionieren. Sind beide vorhanden, gewinnt X-API-Key. Ein fehlender oder fehlerhafter Header liefert 401 mit dem Code authentication_required, und die Antwort sagt nie, ob der Schlüssel nicht existiert oder widerrufen wurde: Diese beiden zu unterscheiden hieße, jemandem das Suchen gültiger Schlüssel zu ermöglichen.

Arten von Schlüsseln

Das Präfix gehört zum Schlüssel, eine geleakte Zeichenkette ist also in einem Protokoll oder bei einem Repository-Scan als Skautik-Zugangsdatum erkennbar. Das ist Absicht: Scanner für Geheimnisse können darauf anschlagen und Sie warnen, bevor jemand anderes den Schlüssel findet.

Berechtigungen

Berechtigungen gelten je Ressource statt als pauschales Paar aus Lesen und Schreiben. Ein Schlüssel wird mit dem Satz erzeugt, den er braucht, und die API lehnt jeden Aufruf ab, dessen Schlüssel die von dieser Route verlangte Berechtigung nicht hat.

Vergeben Sie den engsten Satz, der die Aufgabe erfüllt. Ein Schlüssel für Marktanalysen kann danach weder Kontaktdaten lesen noch ein Angebot zurückziehen, wie schlimm er auch leckt.

Wechsel

Schlüssel verfallen nicht nach Plan, denn erzwungener Verfall führt eher zu einem Ausfall als zu mehr Sicherheit. Wechseln Sie stattdessen bewusst. Eine Organisation kann mehrere Schlüssel zugleich halten, genau damit dies ohne Ausfall geht:

• Legen Sie einen zweiten Schlüssel neben dem genutzten an.
• Rollen Sie ihn aus und bestätigen Sie, dass der Verkehr darauf umgezogen ist.
• Prüfen Sie auf der Schlüsselseite, dass der alte still geworden ist, statt es anzunehmen.
• Widerrufen Sie den alten Schlüssel.

Ein Widerruf wirkt sofort, ohne Übergangsfrist.

Einen Schlüssel geheim halten

• Nur serverseitig. Ein Schlüssel, der in einen Browser oder ein Mobil-Binary ausgeliefert wird, ist ein veröffentlichter Schlüssel, ganz gleich wie verschleiert. Leiten Sie über Ihr eigenes Backend.
• Halten Sie Schlüssel in Umgebungsvariablen oder einem Secret Manager, nie in einem Repository, einem Build-Artefakt oder einem Client-Bundle.
• Nutzen Sie je Umgebung und je Dienst einen eigenen Schlüssel, damit ein Widerruf nicht alles mitreißt.
• Der vollständige Schlüssel wird einmal bei der Erstellung angezeigt und nur als Hash gespeichert. Wir können ihn für Sie nicht wiederherstellen; legen Sie stattdessen einen neuen an.

Wenn ein Schlüssel leckt

Widerrufen Sie ihn zuerst und untersuchen Sie danach: Ein widerrufener Schlüssel kostet Sie eine Auslieferung, ein aktiver geleakter kostet Sie Ihr Kontingent und Ihre Daten.

Schreiben Sie anschließend an security@skautik.com, damit wir auf Nutzung prüfen können, die nicht von Ihnen stammt. Wir beobachten außerdem öffentliche Code-Hoster auf unsere Schlüsselpräfixe und widerrufen einen Schlüssel, den wir offen liegen sehen, und sagen Ihnen Bescheid, wenn wir das tun.

Einen Schlüssel prüfen

GET /v1/api/me liefert Organisation, Tarif und verbleibendes Kontingent hinter einem Schlüssel. Das ist der richtige Aufruf für eine Startprüfung oder einen Health Check, denn er belegt, dass der Schlüssel funktioniert, ohne eine Ressource zu blättern.

Schlüssel verwalten Sie auf der Seite für API-Schlüssel.