API-Schlüssel
API-Schlüssel erzeugen, eingrenzen und widerrufen — der Zugang der externen Systeme zum GraphQL Ihrer Apps.
Die externen Systeme — ein ERP, das Kunden synchronisiert, eine Website, die
Bestellungen anlegt, eine Fakturierungs-Integration — rufen das GraphQL der
Apps mit einem API-Schlüssel auf: einem Geheimnis, das im Header
x-api-key jedes Requests gesendet wird. Die Schlüssel werden auf Ebene der
Plattform verwaltet und zwischen Apps geteilt: Jeder Schlüssel hat einen
Scope — Sie wählen die Apps und, pro App, alle Endpunkte oder nur einige.
Eine Fakturierungs-Integration kann zum Beispiel Konten in der App
Kundenverwaltung lesen und Dokumente in einer anderen App schreiben, mit
einem einzigen Schlüssel.
Nota
Die Schlüssel gehören denen, die die Plattform administrieren: Die Seite API-Schlüssel steht nur Administratorkonten zur Verfügung.
Die Seite API-Schlüssel
Öffnen Sie das Menü API-Schlüssel in der globalen Navigation. Die Liste zeigt alle Schlüssel der Plattform:
| Spalte | Was sie ist |
|---|---|
| Name | Der Name, den Sie dem Schlüssel gegeben haben — identifiziert die Integration. |
| Präfix | Die ersten Zeichen des Schlüssels (z. B. amk_A1b2C3…) — daran erkennen Sie, welcher welcher ist, ohne je den ganzen Schlüssel zu zeigen. |
| Scope | Die Apps, auf die er Zugriff gibt, und, pro App, „alle Endpunkte" oder die Liste der gewährten. |
| Status | aktiv oder widerrufen. |
| Zuletzt verwendet | Wann der Schlüssel zuletzt verwendet wurde — nie, wenn noch nicht. |
Dica
Die Spalte Zuletzt verwendet ist Ihr Aufräumwerkzeug: Ein Schlüssel, der seit Monaten nicht verwendet wurde, ist ein Kandidat für den Widerruf.
Einen API-Schlüssel erstellen
- Klicken Sie auf Neuer API-Schlüssel.
- Geben Sie einen Name des Schlüssels — z. B.
integração-faturação. - Markieren Sie unter Scope — erlaubte Apps und Endpunkte die einzuschließenden Apps. Standardmäßig gewährt jede markierte App „Alle Endpunkte dieser App."
- Um den Zugriff in einer App enger zu ziehen, markieren Sie Auf bestimmte Endpunkte beschränken und wählen die APIs eine nach der anderen. Bei einer Tabellen-API deckt der Grant alle aktiven Operationen ab — die Liste zeigt „gibt Zugriff auf: getContas, addContas, …", damit Sie genau wissen, was Sie gewähren.
- Klicken Sie auf API-Schlüssel generieren.
Den Schlüssel kopieren und verwahren
Nach dem Generieren zeigt das Fenster den Schlüssel im Klartext — ein einziges Mal. Kopieren Sie ihn mit Kopieren und verwahren Sie ihn an einem sicheren Ort (ein Geheimnisverwalter, der Tresor Ihres Teams). Wenn Sie das Fenster schließen, sehen Sie ihn nie wieder — die Plattform bewahrt den Schlüssel nicht im Klartext auf; wenn Sie ihn verlieren, können Sie ihn nur widerrufen und einen anderen generieren.
Atenção
Behandeln Sie den Schlüssel wie ein Passwort: Legen Sie ihn nicht in Quellcode, nicht in URLs und nicht in Benutzer-Bildschirme. Wenn Sie ein Leck vermuten, widerrufen Sie sofort — einen neuen Schlüssel zu generieren kostet Sekunden.
Den Schlüssel verwenden
Der Schlüssel geht im Header x-api-key jedes Requests an den
GraphQL-Endpunkt der App mit:
curl -X POST 'https://o-teu-host/api/graphql/gestao-clientes' \
-H 'content-type: application/json' \
-H 'x-api-key: amk_………' \
-d '{"query":"query { getContas(take: 5) { id nome } }"}'
Der Tab Docs jeder API erzeugt dieses Beispiel (und die JavaScript-Variante) schon mit der richtigen Operation — es fehlt nur Ihr Schlüssel.
Was ein Schlüssel sieht und nicht sieht:
- Nur veröffentlichte APIs — Entwürfe niemals, selbst mit dem Scope der ganzen App.
- Nur, was der Scope gewährt: Eine App außerhalb des Scopes aufzurufen
gibt
403 — API key not authorised for this projectzurück; einen Endpunkt außerhalb des Scopes,403 — API key not authorised for this endpoint. - Immer die Hauptversion der App (oder die veröffentlichte Version der verwendeten Adresse) — niemals die Arbeitsversion eines Developers.
Limits und Fehler
Jeder Schlüssel hat eine Obergrenze von Requests pro Minute. Die Fehlerantworten, die eine Integration behandeln können sollte:
| Antwort | Bedeutung | Was tun |
|---|---|---|
401 |
Schlüssel fehlt, ist ungültig, abgelaufen oder widerrufen. | Prüfen Sie den Header und den Status des Schlüssels in der Liste. |
403 |
Schlüssel gültig, aber ohne Zugriff auf die App oder den Endpunkt. | Passen Sie den Scope an — generieren Sie einen neuen Schlüssel mit dem richtigen Scope. |
429 |
Obergrenze der Requests pro Minute erreicht. | Warten Sie die im Header retry-after angegebene Zeit und wiederholen Sie. |
Einen Schlüssel widerrufen
- Klicken Sie in der Liste auf das Widerrufs-Symbol der Zeile.
- Bestätigen Sie mit Schlüssel widerrufen.
Der Widerruf ist sofort wirksam: Alle Apps, die diesen Schlüssel
konsumieren, verlieren beim nächsten Request den Zugriff. Ein widerrufener
Schlüssel kann nicht reaktiviert werden — er bleibt in der Liste, markiert
als widerrufen, als Aufzeichnung.
Warum nicht…?
- Ich habe den Schlüssel verloren — kann ich ihn noch einmal sehen? Nein. Der Schlüssel im Klartext wird nur im Moment der Erstellung gezeigt. Widerrufen Sie den alten und generieren Sie einen anderen.
- Ich muss Zugriff auf einen weiteren Endpunkt geben — bearbeite ich den Schlüssel? Der Scope wird bei der Erstellung festgelegt. Generieren Sie einen neuen Schlüssel mit dem vollständigen Scope, tauschen Sie ihn in der Integration aus und widerrufen Sie den alten.
- Warum erhält die Integration
403bei einem neuen Endpunkt? Der Schlüssel wurde auf bestimmte Endpunkte beschränkt und der neue steht nicht auf der Liste — dasselbe Heilmittel: neuer Schlüssel mit dem richtigen Scope. - Gibt der Schlüssel Zugriff auf die Bildschirme der App? Nein. Ein Schlüssel spricht nur mit dem GraphQL-Endpunkt. Die Benutzerkonten der App sind etwas anderes, verwaltet in den Einstellungen der App selbst.