Zum Hauptinhalt springen

Wie die Authentifizierung in der Sally API funktioniert

Jede Anfrage an die Sally API, außer der Verfügbarkeitsprüfung, trägt ein Bearer-Token im Header Authorization. Diese Seite erklärt, welche Tokens es gibt, was ein Token sehen darf und wie du herausfindest, wem ein Token gehört.

Authorization: Bearer <token>

Schnellnavigation

  1. Zwei Arten von Token
  2. Was ein Token darf
  3. Herausfinden, wer du bist
  4. Tokens sicher aufbewahren

1. Zwei Arten von Token​

  • Persönliches Zugangstoken mit dem Präfix sally_user_api_. Du legst es in Sally unter Einstellungen > Integrationen > Personal Access Token an. Es hängt an deinem Nutzer und läuft nicht ab, solange du kein Ablaufdatum setzt. Das ist die richtige Wahl für eine Anbindung, die du selbst betreibst, und die, die der Schnellstart nutzt.
  • OAuth-2.1-Zugangstoken, von Sally ausgestellt. Das ist die richtige Wahl, wenn du etwas baust, das andere Unternehmen installieren und bei dem sie sich mit ihrem eigenen Sally-Konto anmelden.

2. Was ein Token darf​

Ein Token handelt als der Nutzer, dem es gehört. Es erreicht genau die Unternehmenskonten, in denen dieser Nutzer Mitglied ist, mit dessen Rolle und Sichtbarkeit. Es gibt kein zweites Rechtemodell zu lernen: Was die Person in der App nicht sieht, sieht auch das Token nicht.

Wichtig

Das merkst du an den Statuscodes. Etwas, das du nicht sehen darfst, antwortet mit 404, nicht mit 403. So verrät eine Antwort nie, dass es die Daten überhaupt gibt. Ein 403 heißt das Gegenteil: Die Ressource existiert und du siehst sie, aber die Operation verlangt eine höhere Rolle, etwa Admin oder Owner. Fehler listet alle Statuscodes.

3. Herausfinden, wer du bist​

Zwei Aufrufe verraten dir, wem das Token gehört und welche Unternehmenskonten es ansprechen darf:

curl "https://api.sally.io/v1.0/me" \
  -H "Authorization: Bearer $SALLY_TOKEN"

4. Tokens sicher aufbewahren​

Empfehlung

Behandle ein Token wie ein Passwort. Schick es nur im Header Authorization mit, nie in einer URL. Gib ihm ein Ablaufdatum, wenn die Anbindung nur vorübergehend ist, und widerrufe ein Token in Sally, sobald es niemand mehr braucht.