Erste Schritte

Authentifizierung

Jede Anfrage enthält einen geheimen Schlüssel des X-Kontos, für das sie bestimmt ist. Du erstellst Schlüssel in der App, kannst sie aufs Lesen beschränken, und sie funktionieren nicht mehr, sobald du sie widerrufst.

API-Schlüssel

Ein Schlüssel besteht aus gl_live_, gefolgt von 32 Buchstaben und Ziffern. Die App zeigt seine ersten 12 Zeichen, etwa gl_live_AbCd, damit du deine Schlüssel auseinanderhalten kannst.
Jeder Schlüssel gehört zu einem X-Konto in Gemlead und sieht nur die Leads, Personas, Kampagnen und Unterhaltungen dieses Kontos.
Der vollständige Schlüssel wird nur einmal angezeigt, beim Erstellen. Gemlead speichert nur einen Hash davon, ein verlorener Schlüssel lässt sich also nicht noch einmal anzeigen. Erstelle dann einen neuen.
Ein Konto kann 20 aktive Schlüssel haben.

Die API ist in den Tarifen Business und Enterprise enthalten, auch in der Testphase. Ist der Inhaber des Kontos im Free- oder Starter-Tarif, antworten Anfragen mit 403 und dem Code plan_required. Die Schlüssel bleiben und funktionieren wieder, sobald das Konto Business oder Enterprise nutzt.

Schlüssel senden

Sende den Schlüssel als Bearer Token im Header Authorization. Für Tools, die kein Bearer Token setzen können, funktioniert auch der Header X-Api-Key.

Eine Anfrage ohne Schlüssel bekommt 401 mit dem Code api_key_missing, mit einem falschen Schlüssel api_key_invalid und mit einem widerrufenen api_key_revoked.

Terminal

# As a bearer token
curl https://gemlead.ai/api/v1/account \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

# Or in X-Api-Key, for tools that cannot set a bearer token
curl https://gemlead.ai/api/v1/account \
  -H "X-Api-Key: $GEMLEAD_API_KEY"

Scopes

Ein Schlüssel hat den Scope read oder read und write. Gib write nur den Tools, die Daten ändern.

Scope	Erlaubt
`read`	Jedes `GET` und `POST /v1/exports`, denn ein Export liest nur.
`write`	Jede Anfrage, die Daten ändert, also `POST`, `PATCH`, `PUT` und `DELETE`.

Ein read-Schlüssel, der Daten ändern will, bekommt 403 mit dem Code insufficient_scope.

Konto abrufen

GET/v1/accountScope readMCPget_account

Gibt das X-Konto zurück, zu dem der Schlüssel gehört. Ein guter erster Aufruf, um einen Schlüssel zu prüfen.

Rückgabe

Das Kontoobjekt, mit business oder enterprise in plan.

Fehler

401api_key_invalid
Der Schlüssel ist falsch.
403plan_required
Der Inhaber des Kontos ist im Free- oder Starter-Tarif.

GET/v1/account

curl https://gemlead.ai/api/v1/account \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Antwort200

{
  "object": "account",
  "id": "a9PzK2vRtM",
  "username": "acme",
  "name": "Acme",
  "profile_image_url": "https://pbs.twimg.com/profile_images/1180044592/acme_400x400.jpg",
  "plan": "business"
}

Schlüssel sicher aufbewahren

Rufe die API nur von deinem Server auf, nie aus einem Browser, einer mobilen App oder dem Code eines öffentlichen Repositorys.
Bewahre Schlüssel in einem Secret Manager oder in einer Umgebungsvariable wie GEMLEAD_API_KEY auf.
Gib jedem Tool einen eigenen Schlüssel, damit du einen widerrufen kannst, ohne die anderen anzufassen.
Um einen Schlüssel zu rotieren, erstelle den neuen, deploye ihn und widerrufe dann den alten in der App.

KI-Assistenten

Claude und ChatGPT verbinden sich per OAuth mit dem MCP-Server. Du meldest dich bei Gemlead an und wählst das X-Konto, ein Schlüssel zum Kopieren ist nicht nötig. Cursor und Claude Code können einen Schlüssel nutzen, den sie wie oben beschrieben senden.