Einen API-Schlüssel anlegen
Zehn Minuten, einmal je Integration. Die Entscheidungen, die zählen, sind der Name und die Scopes; der Rest ist Mechanik.
1. Die Schlüsselliste öffnen
Gehen Sie zu Einstellungen › API-Schlüssel.
Die Seite zeigt jeden Schlüssel des Tenants mit Name / Prefix, seinen Scopes und Created / Expires. Sichtbar ist nur der Prefix — das Secret selbst liegt nirgendwo, wo Sie oder irgendjemand sonst es lesen könnte.
Die Karte oben liefert außerdem den Gateway Endpoint,
https://api.revenexx.com, mit Kopierknopf. Diesen Wert braucht Ihr
Integrator neben dem Schlüssel; alle Pfade hängen von dort unter /v1.
2. Den Schlüssel anlegen
Wählen Sie Create API key.
3. Nach der Integration benennen
Tragen Sie unter General Settings einen Namen ein, der das System bezeichnet, nicht die Person:
| Gut | Schlecht | Warum |
|---|---|---|
erp-order-sync-prod | thomas | Der Schlüssel einer Person geht mit ihr |
bi-nightly-export | key2 | Was Sie nicht identifizieren können, können Sie nicht widerrufen |
wms-stock-push | test | „test" überlebt jedes Mal bis in die Produktion |
sandbox-integrator-mueller | api | Namen sind Ihr Audit-Werkzeug |
Nehmen Sie die Umgebung in den Namen auf, wenn Sie zusätzlich einen
Sandbox-Tenant betreiben. Zwei Schlüssel namens erp-sync in zwei Tenants
sind ein Fehler, der auf ein Deployment wartet.
4. Die Scopes wählen
Unter Scopes & Permissions gibt es zwei Wege, Zugriff zu gewähren, und die meisten Integrationen brauchen beide sparsam.
Vordefinierte Scopes sind breit, einer je Plattformbereich: *, auth,
search, storage, messaging, functions, imports, exports. Haken
Sie nur an, was die Integration tatsächlich nutzt. Ein nächtlicher Preisimport
braucht imports. Er braucht kein messaging.
Custom Scopes sind die engen, und dort sollten die meisten
Integrationen leben. Tragen Sie sie in der Form resource.action ein —
products.read, orders.update, orders.create, inventories.write —
und wählen Sie je Add. Sie sammeln sich unter Selected scopes, wo
Sie versehentlich Hinzugefügtes wieder entfernen können.
* nicht an. Vollzugriff ist für einen Notfall, nicht für
eine Integration, und ein Schlüssel, der ihn an einem Dienstagnachmittag
bekam, trägt ihn drei Jahre später noch. Wissen Sie noch nicht, was die
Integration braucht, geben Sie ihr jetzt die Lese-Scopes und ergänzen Sie
Schreib-Scopes, wenn sie danach fragt — dieses Gespräch dauert fünf Minuten
und erzeugt einen korrekten Schlüssel.Zwei Scope-Fehler verdienen einen Namen, weil beide häufig sind:
- Schreiben gewähren, wo Lesen reicht. Ein ERP, das Bestellungen abholt
und nie ändert, braucht
orders.read, nichtorders.update. - Den ganzen Bereich für eine Aktion gewähren.
importsdeckt jeden Massenimport ab. Schiebt die Integration nur Preise, halten Sie das im Übergabedokument fest, auch wo der Scope nicht enger geht — dann hat das Review in sechs Monaten etwas zum Gegenprüfen.
5. Generieren, und das Secret einmal kopieren
Wählen Sie Generate Key.
Das Secret erscheint einmal, auf einem Bildschirm, der genau das sagt. Es gibt keinen Weg, es wiederzusehen — Schlüssel werden gehasht gespeichert, niemand in Ihrem Unternehmen und niemand bei revenexx kann es abrufen.
Kopieren Sie es direkt an sein Ziel:
| Tun | Nicht tun |
|---|---|
| In den Secret-Manager oder CI-Secret-Store des Integrators einfügen | Per E-Mail schicken |
| In den Credential-Speicher des ERP einfügen | In ein Ticket oder eine Chat-Nachricht legen |
| Die Person, die ihn nutzt, dabeihaben und einmal einfügen | Während eines Workshops ans Whiteboard schreiben |
| In Ihrem Schlüsselinventar notieren, wo er liegt | Den Anzeige-Bildschirm screenshotten |
Wählen Sie dann Done, back to API keys und prüfen Sie, dass der neue Schlüssel mit den erwarteten Scopes in der Liste steht.
6. Testen, bevor jemand dagegen baut
Ein Aufruf beweist die ganze Kette — Schlüssel, Tenant-Header, Scopes und Netzwerkpfad:
GET /v1/orders?limit=1 HTTP/1.1
Host: api.revenexx.com
X-Revenexx-Tenant: acme-eu
X-Revenexx-Api-Key: rvxk_…
| Ergebnis | Bedeutet |
|---|---|
200 mit JSON-Umschlag | Der Schlüssel funktioniert, und der Scope deckt dieses Lesen |
401 Unauthorized | Der Schlüssel ist falsch, vertippt oder widerrufen |
403 Forbidden | Der Schlüssel ist gültig, aber sein Scope deckt das nicht — Scope ergänzen |
400 Bad Request | Der Tenant-Header fehlt oder ist fehlerhaft |
404 Not Found | Keine solche Ressource auf diesem Tenant — die App ist womöglich nicht installiert |
Machen Sie das selbst, von Ihrer eigenen Maschine, bevor Sie irgendetwas übergeben. Es trennt „der Schlüssel ist falsch" von „ihr Code ist falsch" und erspart einen Tag gegenseitiger Schuldzuweisung.
Was Sie prüfen
- Der Schlüssel steht in der Liste, mit dem beabsichtigten Namen und den beabsichtigten Scopes.
- Das Secret liegt an genau einem Ort, und Sie wissen, an welchem.
- Ihr Schlüsselinventar hat eine neue Zeile: Schlüsselname, Integration, Verantwortlicher, Datum, wen man anruft, wenn er widerrufen wird.
- Kein bestehender Schlüssel wurde geweitet, damit das funktioniert.
Wenn es nicht funktioniert
401direkt nach dem Anlegen — das Secret wurde beim Kopieren abgeschnitten. Lange Werte kürzen Chat-Clients und Tabellenzellen. Widerrufen und neu ausstellen.403bei manchen Aufrufen, bei anderen nicht — ein fehlender Capability-Scope. Ergänzen Sie den konkreten, nicht die Wildcard.- Funktioniert vom Laptop, nicht von deren Server — ein Netzwerkproblem, kein Schlüsselproblem. Siehe Häufige API-Probleme.
Weiter
- Webhooks einrichten — die andere Hälfte der meisten Integrationen.
- Häufige API-Aufgaben nach Job — was Sie mit dem Schlüssel tun, jetzt, wo es ihn gibt.