Authentifizierung

Jede Anfrage wird mit einem API-Schlüssel authentifiziert. Senden Sie ihn als Bearer-Token:

Authorization: Bearer gsk_live_xxx

Ist ein Bearer-Token in Ihrem Stack unpraktisch, wird auch der Header x-api-key: gsk_live_xxx akzeptiert. Ohne Schlüssel erhält jede Anfrage 401 mit title: invalid_key.

Schlüsselformat

gsk_live_<id>_<geheimnis> oder gsk_test_<id>_<geheimnis>. Ein gsk_live-Schlüssel erledigt echte Arbeit, die berechnet wird. Ein gsk_test-Schlüssel läuft in der Sandbox: Werkzeuge werden simuliert, nichts wird berechnet, und Objekte, Leads oder andere echte Daten lassen sich damit nicht ändern. Den Schlüsseltyp wählen Sie beim Erstellen.

Das Geheimnis wird einmal beim Erstellen angezeigt. GREM speichert nur seinen Hash, ein verlorener Schlüssel lässt sich nicht wiederherstellen - erstellen Sie einen neuen und widerrufen Sie den alten.

Schlüssel verwalten

Im Kabinett unter API → Schlüssel:

• Erstellen mit einer Bezeichnung. In den erweiterten Einstellungen wählen Sie Bereiche und eine Gültigkeit in Tagen. Ohne Auswahl erhält der Schlüssel alle Bereiche.
• Rotieren - ein neues Geheimnis ausstellen; das alte funktioniert noch 24 Stunden, damit Sie es in der Integration austauschen können.
• Widerrufen - der Schlüssel funktioniert sofort und dauerhaft nicht mehr.

Der Status steht in der Liste: active - funktioniert; suspended - API-Zugriff von einem Administrator pausiert (umkehrbar, der Schlüssel bleibt erhalten); revoked - widerrufen. Ein Schlüssel mit Ablaufdatum wird danach nicht mehr akzeptiert (401).

Agenturschlüssel

Inhaber oder Manager einer Agentur können einen Schlüssel im Namen der Agentur ausstellen: Schalten Sie die Schlüsselliste auf den Bereich «Agentur» um. Ein solcher Schlüssel:

• sieht die Objekte und Leads der Agentur, nicht die persönlichen;
• kann Leads aus dem gemeinsamen Pool der Agentur übernehmen und zurückgeben (Leads);
• kann Objekte in die Agentur verschieben und einen Verantwortlichen zuweisen (Objekte).

Ein Schlüssel kann an einen bestimmten Agenten gebunden werden - dann handelt er als dieser Agent mit dessen Rechten.

Bereiche

Jeder Schlüssel trägt eine Menge von Bereichen. Ein Aufruf ohne den nötigen Bereich liefert 403 mit title: forbidden_scope. Welcher Bereich nötig ist, steht bei jeder Operation in /openapi.json (Feld x-required-scope).

Ohne Bereich verfügbar sind GET /ping, GET /me, GET /dictionaries, GET /objects, GET /voices, GET /tools/status und GET /works.

Welcher Schlüssel ist das

curl https://developers.grem.capital/api/v1/me \
  -H "Authorization: Bearer gsk_live_xxx"

GET /me liefert Kennung und Präfix des Schlüssels, wem er gehört (subjectType: user oder agency, subjectId, bei einem Agentenschlüssel agencyMemberId), die erteilten Bereiche, die für genau diesen Schlüssel geltenden Limits (rateLimit.rpm pro Minute und rateLimit.rpd pro Tag) und das Ablaufdatum. Das Geheimnis wird nie zurückgegeben. Kostenlos.

Sicherheit

• Bewahren Sie Schlüssel in serverseitigen Umgebungsvariablen oder einem Secret-Manager auf.
• Pro Integration ein eigener Schlüssel mit nur den nötigen Bereichen - der Widerruf eines Schlüssels betrifft die anderen nicht.
• Rotieren Sie Schlüssel planmäßig.
• Anfragen werden nur über HTTPS angenommen.

Verwandte Artikel

• Fehler - 401 und 403 im Detail.
• Limits und Abrechnung - was rpm und rpd bedeuten.