Zum Hauptinhalt springen
Hilfecenter

Authentifizieren: Gerätepasswort & API-Token

Ein Gerätepasswort (API-Token) anlegen und per Basic Auth nutzen – inklusive Hinweisen zu Zwei-Faktor-Authentifizierung und der nötigen Berechtigung.

Voraussetzungen

  • Ein teamspace-Konto mit der Berechtigung „Synchronisation“

Um die API zu nutzen, authentifizierst du dich mit einem Gerätepasswort (auch API-Token genannt). Das ist eine eigene Zugangsdaten-Kombination für Anwendungen und Skripte – getrennt von deinem normalen Login. Der Vorteil: Du kannst ein Gerätepasswort jederzeit einzeln widerrufen, ohne dein Hauptpasswort zu ändern, und für verschiedene Anwendungen mehrere Passwörter anlegen.

1. Gerätepasswort anlegen

Ein Gerätepasswort erstellst du in deinen persönlichen Einstellungen:

Persönliche Einstellungen → Reiter „Geräte" → „Neues Gerätepasswort"
  1. Öffne die Persönlichen Einstellungen.
  2. Wechsle in den Reiter „Geräte”.
  3. Klicke auf „Neues Gerätepasswort”.
  4. Vergib einen Namen für das Gerät (z. B. „Import-Skript Buchhaltung”).
  5. Klicke auf „Speichern”.

Anschließend zeigt das System die Geräte-ID und das Passwort an. Mit diesen beiden Werten meldet sich deine Anwendung an der API an.

Persönliche Einstellungen → Reiter „Geräte
Persönliche Einstellungen → Reiter „Geräte" – Dialog „Neues Gerätepasswort"

Das Passwort wird nur einmal angezeigt. Notiere es sofort an einem sicheren Ort. Hast du es verloren, kannst du es jederzeit über „Passwort ändern” neu erzeugen – das alte wird dann ungültig.

2. Per Basic Auth anmelden (Token-Authentifizierung)

Jede reguläre API-Anfrage authentifizierst du per HTTP Basic Authentication – und zwar mit Geräte-ID und Token, nicht mit deiner E-Mail und deinem normalen Passwort. Geräte-ID und Token werden dazu als id:token Base64-kodiert in den Authorization-Header geschrieben:

// Geräte-ID und Token aus dem lokalen Speicher der App
var credsB64 = window.btoa(device._id + ':' + device.token);

var xhr = new XMLHttpRequest();
xhr.open('GET', url, true);
xhr.setRequestHeader('Authorization', 'Basic ' + credsB64);
xhr.send();

Token statt Passwort: Speichere in deiner Anwendung nur Geräte-ID und Token – niemals das ursprüngliche Passwort. Wird ein Gerät kompromittiert, löschst du genau dieses Gerät; alle anderen Zugänge bleiben aktiv.

3. Alternative: Token direkt über die API erzeugen

Du kannst ein Gerät auch direkt über die API anlegen, statt über die Oberfläche. Mit deinen Login-Daten (E-Mail + Passwort) erreichst du ausschließlich die device-Ressource – sie liefert dir den Token, mit dem du dich danach anmeldest:

POST  server/api/device
{
  "email": "test@5point.de",
  "password": "password",
  "deviceName": "test5p",
  "deviceType": "de.fivepoint.other"
}

Stimmen E-Mail und Passwort, antwortet der Server mit der neuen Geräte-Ressource. Sie enthält die Geräte-ID (_id) und den Token (token), die du für alle weiteren Anfragen brauchst:

{
  "_id": "10001234",
  "token": "D1C2B3A4",
  "deviceName": "test5p",
  "deviceType": "unknown"
}

Nicht bei aktiver Zwei-Faktor-Authentifizierung: Ist für dein Konto 2FA aktiviert, steht dieser Weg nicht zur Verfügung. Lege das Gerätepasswort dann wie in Schritt 1 über die Weboberfläche an.

Tipp: Lade beim Start deiner App zuerst die eigene device-Ressource. Klappt das, weißt du sofort, dass der Token noch gültig ist.

Hinweise

  • Berechtigung fehlt? Siehst du den Reiter „Geräte” oder die Option zum Anlegen eines Gerätepassworts nicht, fehlt dir die Berechtigung „Synchronisation”. Bitte deinen Administrator, sie dir zu erteilen.
  • Lege für jede Anwendung ein eigenes Gerätepasswort an – so kannst du einzelne Zugänge gezielt sperren, ohne andere zu beeinträchtigen.
  • Für Geräte und Dienste ohne persönlichen Nutzer (z. B. ein Zeiterfassungsterminal) ist statt eines Gerätepassworts eine API-Zugangsberechtigung der richtige Weg.
  • Weitere Sicherheitsempfehlungen findest du in API-Sicherheit & Berechtigungen.

Verwandte Themen