Service-Accounts
Ein Service-Account ist ein Satz Maschinen-Zugangsdaten: eine Client-ID und ein Client-Secret, mit denen sich ein externes System (eine Integration, ein Skript, eine Partnerplattform) an der LIKE MAGIC API authentifizieren kann, ohne den Login einer Person zu nutzen. Statt ein Mitarbeiterpasswort zu teilen, gibst du einen dedizierten Account aus und gewährst ihm genau die Berechtigungen („Scopes"), die er braucht.
Dieser Artikel richtet sich an den Administrator oder Entwickler, der diese Zugangsdaten bereitstellt.
1. Wer kann das nutzen
Service-Accounts werden in der Operations Platform unter Einstellungen → Konto → Service-Konten verwaltet. Zum Anlegen oder Bearbeiten brauchst du die Rolle Account Administrator (account-admin), Account Viewer (account-viewer) sieht die Seite nur lesend. Die Seite benötigt das Platform Pricing. Auf Core wird sie gesperrt und mit Upgrade-Hinweis angezeigt. Siehe Pricing-Tiers. Da ein Service-Account API-Zugriff gewährt, behandle das Erstellen als sicherheitsrelevante Aktion.
2. Wann ein Service-Account sinnvoll ist
Nutze einen Service-Account immer dann, wenn ein System und keine Person die API aufrufen muss, zum Beispiel:
- eine Partnerplattform, die Reservierungen liest oder Bestellungen schreibt,
- eine Integration, die Türschlösser oder Aufgaben verwaltet,
- ein Backend-Job, der Events oder Metriken liest.
Verwende für Automatisierung nicht den Login eines Mitarbeitenden: Mitarbeiter-Logins sind an Personen gebunden, tragen menschliche Rollen und verschwinden, wenn die Person geht.
3. Einen Service-Account erstellen
Beim Erstellen eines Service-Accounts gibst du an:
- einen Namen: eine menschenlesbare Bezeichnung, damit du Integrationen unterscheiden kannst,
- eine Client-ID: die Kennung, die das externe System vorlegt,
- ein Client-Secret: die Passwort-Hälfte der Zugangsdaten,
- einen oder mehrere Scopes: die Berechtigungen, die der Account nutzen darf.
Einen neuen Account erstellst du über Neues Service-Konto, bearbeiten und löschen kannst du ihn auf demselben Bildschirm. Die Client-ID wird beim Erstellen festgelegt und lässt sich danach nicht umbenennen, eine andere Client-ID bedeutet also ein neues Service-Konto.
Derselbe Bildschirm trägt einen Block Verbindungsdaten mit den Werten, die das externe System neben den Zugangsdaten braucht: Token-Endpunkt, API-Basis-URL und deinen Mandant.
4. Scopes (Nur gewähren, was nötig ist)
Ein Scope ist eine einzelne, eng gefasste Berechtigung. Jeder Scope steht für eine bestimmte Funktion. Viele gibt es in einer Lese- und einer Schreibvariante, sodass du reinen Lesezugriff gewähren kannst, wo eine Integration nur das braucht; andere existieren nur als Lese- oder nur als Schreibrecht. Scopes decken Bereiche ab wie:
| Bereich | Beispiel-Scopes |
|---|---|
| Reservierungen | reservation.read, reservation.write |
| Türzugang & Schlösser | door_access.read, door_access.write, lock.read, lock.write |
| Aufgaben | task.read, task.write, task_template.read, task_template.write, task_log.read |
| Gästenachrichten | guest_conversation.read, guest_conversation.write, guest_message_attachment.read |
| Profile & Identität | user_profile.read, user_profile.write, actor.read, actor_group.read, magic_id.read |
| Units & Properties | unit.read, unit_group.read, property.read |
| Webhooks & Events | webhook_subscription.read, webhook_subscription.write, event_log.read |
| Bestellungen & Services | order_item.write, service.read, email_template.write, metric.read |
🔑 Gewähre die geringsten Rechte, die funktionieren. Wenn eine Integration nur Reservierungen liest, gib ihr den Read-Scope und sonst nichts. Einen Scope kannst du später jederzeit hinzufügen; Über-Gewähren ist der schwerer rückgängig zu machende Fehler.
5. Das Secret sicher handhaben
Das Client-Secret ist ein Credential. Behandle es wie ein Passwort:
- Speichere es im Secret-Store des externen Systems, niemals in einem geteilten Dokument, einer Chat-Nachricht oder im Quellcode.
- Übergib es über einen sicheren Kanal.
- Wenn du einen Leak vermutest, rotiere es (siehe Abschnitt 6) sofort.
6. Bearbeiten und Widerrufen
Du kannst einen Service-Account bearbeiten, um ihn umzubenennen, seine Scopes zu ändern oder ein neues Client-Secret zu erzeugen, und du kannst ihn löschen, um den Zugriff vollständig zu widerrufen. Das Löschen stoppt sofort jedes System, das diese Zugangsdaten nutzt, an der Authentifizierung. Damit kappst du eine kompromittierte oder ausgemusterte Integration.
ℹ️ Hinweis: Das Entfernen eines Scopes wirkt für neue Aufrufe; eine Integration, die darauf angewiesen war, erhält Berechtigungsfehler. Das ist das beabsichtigte Signal, dass ihr Zugriff reduziert wurde.
7. Fazit
Service-Accounts sind der sichere Weg, Systeme, nicht Personen, die LIKE MAGIC API nutzen zu lassen. Erstelle einen pro Integration, beschränke ihn auf genau die benötigten Berechtigungen, schütze das Secret und widerrufe ihn, sobald die Integration ausgemustert oder kompromittiert ist.