Authentifizierung

Der Header

Das Schema ist Bearer. Ein fehlender, fehlerhafter, unbekannter oder widerrufener Schlüssel ergibt stets 401 — die vier Fälle unterscheiden sich über das Feld code, nie über den HTTP-Status.

Authorization: Bearer gaff_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

const res = await fetch('https://getaff.org/api/v1/me', {
  headers: { Authorization: `Bearer ${process.env.GETAFF_API_KEY}` },
});

if (res.status === 401) {
  // Read the code, not the message: it is the stable part of the contract.
  const { error } = await res.json();
  throw new Error(`GetAff rejected the key: ${error.code}`);
}

Nur einmal sichtbar

Wir speichern lediglich einen Hashwert Ihres Schlüssels, nie seinen Wert. Niemand — auch wir nicht — kann ihn Ihnen nach der Erstellung erneut zeigen. Wenn Sie ihn verlieren, widerrufen Sie ihn und erstellen einen neuen: ein völlig unkritischer Vorgang.

Wo Sie ihn aufbewahren

Ein API-Schlüssel gewährt Zugriff auf Ihre Einnahmen. Behandeln Sie ihn wie ein Produktionspasswort.

• In einem Secret-Manager, ersatzweise in einer Umgebungsvariable.
• Niemals in einem Code-Repository, auch nicht in einem privaten: Private Repositories werden irgendwann geklont.
• Niemals in einem Ticket, einer Nachricht oder einem Screenshot.
• Ein Schlüssel je Integration, damit ein Widerruf die übrigen nicht stilllegt.

Wenn ein Schlüssel abfließt

Widerrufen Sie ihn sofort auf der Seite „API-Schlüssel“. Der Widerruf greift beim nächsten Aufruf. Der Eintrag bleibt erhalten, als widerrufen markiert und mit dem Datum der letzten Nutzung: Nur so lässt sich feststellen, ob der Schlüssel nach dem Leck noch verwendet wurde.

Berechtigungen

Jeder Schlüssel trägt heute die Berechtigung read, die einzige, die existiert. Das Feld steht bereits in der Antwort von /v1/me, damit ein heute geschriebener Client weiterläuft, sobald weitere Berechtigungen hinzukommen.