Aan de slag

Authenticatie

Elk request bevat de geheime sleutel van het X-account waar het over gaat. Je maakt sleutels aan in de app, kunt ze beperken tot alleen lezen, en ze werken niet meer zodra je ze intrekt.

API-sleutels

Een sleutel is gl_live_ gevolgd door 32 letters en cijfers. De app toont de eerste 12 tekens, zoals gl_live_AbCd, zodat je je sleutels uit elkaar kunt houden.
Elke sleutel hoort bij één X-account in Gemlead en ziet alleen de leads, persona's, campagnes en gesprekken van dat account.
De volledige sleutel zie je maar één keer, bij het aanmaken. Gemlead bewaart er alleen een hash van, dus een kwijtgeraakte sleutel is niet meer op te vragen. Maak dan een nieuwe aan.
Een account kan 20 actieve sleutels hebben.

De API zit in de abonnementen Business en Enterprise, proefperiode inbegrepen. Heeft de eigenaar van het account Free of Starter, dan krijgen requests een 403 met de code plan_required. De sleutels blijven bestaan en werken weer zodra het account op Business of Enterprise staat.

De sleutel meesturen

Stuur de sleutel als bearer token mee in de header Authorization. De header X-Api-Key werkt ook, voor tools die geen bearer token kunnen instellen.

Een request zonder sleutel krijgt een 401 met de code api_key_missing, met een verkeerde sleutel wordt dat api_key_invalid en met een ingetrokken sleutel 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

Een sleutel heeft de scope read, of read en write. Geef write alleen aan tools die gegevens wijzigen.

Scope	Toegestaan
`read`	Elke `GET`, en `POST /v1/exports`, want een export leest alleen.
`write`	Elk request dat gegevens wijzigt, `POST`, `PATCH`, `PUT` en `DELETE`.

Een read-sleutel die gegevens probeert te wijzigen, krijgt een 403 met de code insufficient_scope.

Het account ophalen

GET/v1/accountScope readMCPget_account

Geeft het X-account terug waar de sleutel bij hoort. Een goede eerste aanroep om een sleutel te testen.

Resultaat

Het accountobject, met plan op business of enterprise.

Fouten

401api_key_invalid
De sleutel klopt niet.
403plan_required
De eigenaar van het account heeft het abonnement Free of Starter.

GET/v1/account

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

Response200

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

Sleutels veilig bewaren

Roep de API alleen aan vanaf je server, nooit vanuit een browser, een mobiele app of de code van een openbare repository.
Bewaar sleutels in een secret manager of een omgevingsvariabele zoals GEMLEAD_API_KEY.
Geef elke tool een eigen sleutel, zodat je er één kunt intrekken zonder aan de andere te komen.
Wil je een sleutel roteren, maak dan eerst de nieuwe aan, deploy hem en trek daarna de oude in via de app.

AI-assistenten

Claude en ChatGPT maken via OAuth verbinding met de MCP-server. Je logt in bij Gemlead en kiest het X-account, je hoeft geen sleutel te kopiëren. Cursor en Claude Code kunnen een sleutel gebruiken, die je op dezelfde manier meestuurt als hierboven.