Die REST API von Xcellerate OPS mit persönlichen API-Schlüsseln nutzen

Xcellerate OPS bietet eine dokumentierte REST API (v1). Damit verbinden Sie eigene Tools, Skripte oder Automatisierungsplattformen mit Tickets, Firmen, Kontakten, Deals, Projekten, Zeiteinträgen, Assets und mehr. Jeder Benutzer legt seine eigenen API-Schlüssel in seinem Profil an, und ein Schlüssel kann genau das, was dieser Benutzer in der App kann, nicht mehr. Diese Anleitung richtet sich an technische Admins von MSPs und Dienstleistungsunternehmen.

TL;DR

• Legen Sie in Ihrem Profil unter API keys einen Schlüssel an und kopieren Sie das Token sofort: Es wird nur einmal angezeigt.
• Senden Sie bei jeder Anfrage zwei Header mit: Authorization: Bearer <token> und X-Tenant-Id.
• Ein Schlüssel erbt die Rechte Ihres Benutzers. Standardmäßig gelten 120 Anfragen pro Minute und Schlüssel.

Bevor Sie beginnen

• Jeder Mitarbeiter kann für sich selbst Schlüssel anlegen. Eine Admin-Rolle ist nicht nötig.
• Was ein Schlüssel darf, entspricht eins zu eins Ihren Teamberechtigungen. Was in der App gesperrt ist, ist auch in der API gesperrt.
• Sie brauchen einen HTTP-Client, der Header senden kann: ein Skript, eine Automatisierungsplattform oder Ihre eigene Anwendung.
• Pro Benutzer sind bis zu 20 aktive Schlüssel möglich.

Hinweis: Der Bereich für API-Schlüssel ist in der App nur auf Englisch verfügbar. Die Bezeichnungen unten sind daher englisch.

Einen API-Schlüssel anlegen und nutzen

Schritt 1: API-Schlüssel öffnen

Öffnen Sie Ihr Profil und dort den Bereich API keys (API-Schlüssel).

Schritt 2: Schlüssel anlegen

Geben Sie dem Schlüssel einen Namen, der seinen Zweck beschreibt. Wählen Sie, ob er nur lesen oder auch schreiben darf, und legen Sie bei Bedarf ein Ablaufdatum in der Zukunft fest. Schlüssel sind schreibgeschützt, sofern Sie sie nicht mit Schreibzugriff anlegen. Wenn Sie nur Daten lesen müssen, bleiben Sie bei Lesezugriff.

Schritt 3: Token kopieren

Nach dem Anlegen zeigt OPS den Hinweis „Copy your new API key now — it will not be shown again.“ Kopieren Sie das Token sofort und bewahren Sie es sicher auf. Tokens beginnen mit xok_. Geht es verloren, legen Sie einen neuen Schlüssel an.

Schritt 4: Workspace-ID kopieren

Im selben Bereich steht die ID Ihres Workspace (Tenant-ID). Kopieren Sie sie mit der Schaltfläche Copy (Kopieren). Sie brauchen sie bei jeder Anfrage.

Schritt 5: Erste Anfrage senden

Testen Sie Ihren Schlüssel mit einer einfachen Anfrage an /api/v1/me und beiden Headern:

GET /api/v1/me
Authorization: Bearer <token>
X-Tenant-Id: <workspace id>

Der Link API documentation ↗ (API-Dokumentation) im Bereich öffnet die interaktive Dokumentation. Prüfen Sie dort die richtige Basisadresse und die verfügbaren Endpoints.

Schritt 6: Nicht mehr genutzte Schlüssel widerrufen

Sie widerrufen einen Schlüssel in derselben Liste. Zu jedem Schlüssel sehen Sie, wann er zuletzt verwendet wurde. So erkennen Sie schnell Schlüssel, die niemand mehr braucht.

Was nach dem Verbinden passiert

• Format: JSON für Anfragen und Antworten. Listen werden per Cursor paginiert.
• Umfang: unter anderem Firmen, Kontakte, CRM-Interaktionen, benutzerdefinierte Felder, Tickets und Ticket-Zeitpläne, Projekte mit Planung und Finanzen, Zeiteinträge, Spesen, Abwesenheiten, Arbeitszeit, Assets und CMDB, Software, Services, Changes, Problems, Major Incidents, Releases, Wissensdatenbank, Verkaufschancen, Preislisten, wiederkehrende Rechnungen, Berichte, SLA- und XLA-Berichte, Anrufe und Aufzeichnungen sowie das Protokoll der KI-Aktionen. Die vollständige Liste steht in der API-Dokumentation.
• Kundenportal: Kunden, die Ihr Kundenportal nutzen, können dort eigene Schlüssel anlegen. Diese sehen nur ihre eigenen Daten.

Wie OPS den Zugriff schützt, lesen Sie unter Sicherheit und Zugriffskontrolle. Alle Anbindungen finden Sie unter EU-Integrationen und Sicherheit.

Gut zu wissen

• Rate Limit: standardmäßig 120 Anfragen pro Minute und Schlüssel. RMM Labs kann das für einen Workspace auf Anfrage erhöhen. Jede Antwort enthält die Header X-RateLimit-Limit und X-RateLimit-Remaining.
• Fehlgeschlagene Anmeldungen: Wiederholte fehlgeschlagene Authentifizierungen von derselben Adresse werden vorübergehend gesperrt.
• Schlüssel gehören zu einer Person. Wird ein Benutzer deaktiviert, werden seine Schlüssel widerrufen und gesperrt. Integrationen, die darauf laufen, funktionieren dann nicht mehr. Planen Sie das beim Ausscheiden von Mitarbeitenden ein.
• Persönliche Einstellungen, etwa zur Kalendersynchronisation, sind über die API nicht verfügbar.

Fehlerbehebung

• 401 unauthenticated „Invalid API credentials.“ Das Token ist falsch, abgelaufen oder widerrufen, die X-Tenant-Id fehlt oder stimmt nicht, der Workspace ist gesperrt oder der Benutzer deaktiviert. Alle Fälle liefern bewusst dieselbe Antwort.
• 429 rate_limited „Too many requests.“ Warten Sie die Sekunden aus dem Header Retry-After ab.
• 429 „Too many failed authentication attempts.“ Ihre IP-Adresse ist nach wiederholten Fehlversuchen vorübergehend gesperrt.
• „You have reached the maximum number of API keys.“ Sie haben 20 aktive Schlüssel. Widerrufen Sie zuerst einen.

Loslegen

Möchten Sie OPS mit Ihren eigenen Skripten und Tools verbinden? Kostenlos starten und den ersten API-Schlüssel im Profil anlegen.