Premiers pas

Authentification

Chaque requête inclut une clé secrète du compte X sur lequel elle agit. Tu crées les clés dans l'app, tu peux les limiter à la lecture, et elles cessent de fonctionner dès que tu les révoques.

Clés API

Une clé, c'est gl_live_ suivi de 32 lettres et chiffres. L'app affiche ses 12 premiers caractères, comme gl_live_AbCd, pour que tu distingues tes clés.
Chaque clé appartient à un seul compte X dans Gemlead et ne voit que les leads, personas, campagnes et conversations de ce compte.
La clé complète ne s'affiche qu'une fois, à sa création. Gemlead n'en garde qu'un hash, une clé perdue ne peut donc plus être affichée. Crées-en une nouvelle.
Un compte peut avoir 20 clés actives.

L'API est incluse dans les plans Business et Enterprise, essai compris. Quand le propriétaire du compte est sur le plan Free ou Starter, les requêtes reçoivent une erreur 403 avec le code plan_required. Les clés sont conservées et fonctionnent à nouveau dès que le compte passe en Business ou Enterprise.

Envoyer la clé

Envoie la clé en bearer token dans le header Authorization. Le header X-Api-Key marche aussi, pour les outils qui ne savent pas envoyer de bearer token.

Sans clé, une requête reçoit une erreur 401 avec le code api_key_missing. Avec une clé incorrecte, le code est api_key_invalid, et avec une clé révoquée, 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

Une clé a le scope read, ou read et write. Ne donne write qu'aux outils qui modifient des données.

Scope	Autorise
`read`	Tous les `GET`, et `POST /v1/exports` puisqu'un export ne fait que lire.
`write`	Toutes les requêtes qui modifient des données, `POST`, `PATCH`, `PUT` et `DELETE`.

Une clé read qui essaie de modifier des données reçoit une erreur 403 avec le code insufficient_scope.

Récupérer le compte

GET/v1/accountScope readMCPget_account

Renvoie le compte X auquel appartient la clé. Un bon premier appel pour tester une clé.

Renvoie

L'objet compte, avec son plan à business ou enterprise.

Erreurs

401api_key_invalid
La clé est incorrecte.
403plan_required
Le propriétaire du compte est sur le plan Free ou Starter.

GET/v1/account

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

Réponse200

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

Protéger tes clés

Appelle l'API depuis ton serveur uniquement, jamais depuis un navigateur, une app mobile ou le code d'un dépôt public.
Garde tes clés dans un gestionnaire de secrets ou une variable d'environnement comme GEMLEAD_API_KEY.
Donne à chaque outil sa propre clé, pour pouvoir en révoquer une sans toucher aux autres.
Pour renouveler une clé, crée la nouvelle, déploie-la, puis révoque l'ancienne dans l'app.

Assistants IA

Claude et ChatGPT se connectent au serveur MCP avec OAuth. Tu te connectes à Gemlead et tu choisis le compte X, sans clé à copier. Cursor et Claude Code peuvent utiliser une clé, envoyée de la même façon que ci-dessus.