Andere Programme anbinden — API-Tokens und Webhooks

Worum es geht

Zwei Wege verbinden BrowserDesk mit anderen Programmen:

• API-Token: Ein Programm — Ihr PSA, ein Skript, ein Monitoring — meldet sich damit an der Konsolen-API an und liest oder ändert Geräte, Tickets und Sitzungen, so wie es die gewählte Rolle erlaubt.
• Webhook: BrowserDesk meldet Ereignisse von selbst an eine Adresse Ihres Systems — neue Tickets, Statuswechsel, Notizen, Beginn und Ende von Sitzungen, Alarme. Alternativ holt Ihr System sie ab.

Für ServiceNow, Jira Service Management und Autotask gibt es fertige Anbindungen (G16).

Das brauchen Sie

• API-Token: ein eigenes Relay und ein Konto als System-Administrator des Relays. In der Cloud legt nur der Betreiber Tokens an.
• Webhook: das Ticketsystem im Zugang (Cloud gebucht, eigenes Relay in der Lizenz; nie Free) — G14 — und eine Adresse, die der Relay erreicht.

So geht's

API-Token anlegen (eigenes Relay)

1. In der Konsole unten links Benutzer → Seite Benutzer & Rollen → API-Tokens ….
2. Name eintragen (z. B. „HaloPSA“), Rolle wählen (Nur lesen, Techniker, Supervisor oder SCIM-Bereitstellung), Gültig wählen (30 Tage bis 1 Jahr) und optional die Zugänge ankreuzen — keiner gewählt heißt: alle.
3. Token anlegen. Das Token erscheint nur jetzt (Nur jetzt sichtbar:) — Token kopieren und sicher ablegen.
4. Im anderen Programm das Token im Kopf jeder Anfrage mitgeben: Authorization: Bearer bda_… — zum Beispiel curl -H "Authorization: Bearer bda_…" https://<ihr-relay>/admin/api/devices?tenant=<zugang>.

So benutzen im selben Dialog nennt die Einzelheiten. Widerrufen: in der Liste Widerrufen — es gilt sofort.

Webhook einrichten

1. Support › Tickets → Reiter Einstellungen → Anbindung (bei mehreren Zugängen oben den Zugang wählen).
2. Haken Anbindung aktiv setzen.
3. Webhook-URL eintragen und mit Secret erzeugen ein Webhook-Secret erzeugen. Der Wert erscheint einmal im Klartext — in Ihr System übernehmen.
4. Oder statt Webhook abholen: Schlüssel erzeugen für den API-Schlüssel (Pull); Ihr System ruft dann GET /api/events?after=<nummer> mit dem Kopf X-BD-Api-Key ab.
5. Anbindung speichern.

Daran sehen Sie, dass es geklappt hat

• Token: Die Liste zeigt den Token mit Gültig bis und Zuletzt benutzt. Eine Anfrage mit dem Token liefert Daten statt einer Absage; was das Token ändert, steht im Audit-Log unter api:<Name> (G17).
• Webhook: Bei einem neuen Ticket kommt bei Ihrer Adresse ein POST an, mit den Köpfen X-BD-Event, X-BD-Event-Id und X-BD-Signature: sha256=… (HMAC-SHA256 des Rumpfs mit Ihrem Secret).

Gut zu wissen

• Rolle höchstens Supervisor: Ein Token verwaltet nie Benutzer, Tokens, Zugänge oder die Konfiguration des Relays. Höchstens 365 Tage gültig.
• Wie ein Kennwort behandeln: Der Relay speichert das Token nicht lesbar; wer es hat, arbeitet mit dessen Rolle.
• Nicht für die Remote-Konsole: Ein API-Token öffnet keine Kommandozeile auf einem Gerät.
• „SCIM-Bereitstellung“ gilt nur für die Benutzerverwaltung über SCIM, nicht für die Konsolen-API (B4).
• Ereignisse: ticket.created, ticket.status, ticket.note, session.started, session.ended sowie device.alert und device.alert.cleared (nur Alarmregeln mit Haken „Webhook“). Empfänger müssen unbekannte Ereignisse überspringen können.
• Sitzung aus dem PSA öffnen geht ohne Token über einen Link: https://<ihr-relay>/app/?tenant=<zugang>&id=<gerätekennung>&ticket=<nummer>.
• Cloud: API-Tokens für Ihren Zugang gibt es noch nicht zum Selbstanlegen — schreiben Sie an info@browserdesk.de. Webhook und Abruf gehen mit gebuchtem Ticketsystem.
• Einen Rückweg (PSA ändert Tickets in BrowserDesk) und eine OpenAPI-Beschreibung gibt es noch nicht.

Wenn es nicht klappt