Primeros pasos

Autenticación

Cada solicitud lleva una clave secreta de la cuenta de X con la que trabaja. Las claves se crean en la app, puedes limitarlas a lectura y dejan de funcionar en cuanto las revocas.

Claves API

Una clave es gl_live_ seguido de 32 letras y cifras. La app muestra sus 12 primeros caracteres, como gl_live_AbCd, para que distingas tus claves.
Cada clave pertenece a una cuenta de X en Gemlead y solo ve los leads, buyer personas, campañas y conversaciones de esa cuenta.
La clave completa solo se muestra una vez, al crearla. Gemlead guarda solo un hash, así que una clave perdida no se puede volver a mostrar. Crea una nueva.
Una cuenta puede tener 20 claves activas.

La API viene con los planes Business y Enterprise, prueba incluida. Si el propietario de la cuenta tiene el plan Free o Starter, las solicitudes responden 403 con el código plan_required. Las claves se conservan y vuelven a funcionar en cuanto la cuenta pasa a Business o Enterprise.

Envía la clave

Envía la clave como bearer token en el encabezado Authorization. El encabezado X-Api-Key también funciona, para las herramientas que no pueden enviar un bearer token.

Sin clave, la respuesta es 401 con el código api_key_missing, con una clave incorrecta api_key_invalid y con una revocada 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

Una clave tiene el scope read, o read y write. Da write solo a las herramientas que modifican datos.

Scope	Permite
`read`	Todos los `GET`, y también `POST /v1/exports`, ya que una exportación solo lee datos.
`write`	Todas las solicitudes que modifican datos, `POST`, `PATCH`, `PUT` y `DELETE`.

Una clave read que intenta modificar datos recibe un 403 con el código insufficient_scope.

Obtener la cuenta

GET/v1/accountScope readMCPget_account

Devuelve la cuenta de X a la que pertenece la clave. Una buena primera llamada para comprobar una clave.

Devuelve

El objeto account, con su plan en business o enterprise.

Errores

401api_key_invalid
La clave es incorrecta.
403plan_required
El propietario de la cuenta tiene el plan Free o Starter.

GET/v1/account

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

Respuesta200

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

Protege tus claves

Llama a la API solo desde tu servidor, nunca desde un navegador, una app móvil o el código de un repositorio público.
Guarda las claves en un gestor de secretos o en una variable de entorno como GEMLEAD_API_KEY.
Da a cada herramienta su propia clave, para poder revocar una sin tocar las demás.
Para rotar una clave, crea la nueva, despliégala y después revoca la antigua en la app.

Asistentes de IA

Claude y ChatGPT se conectan al servidor MCP con OAuth. Inicias sesión en Gemlead y eliges la cuenta de X, no hay ninguna clave que copiar. Cursor y Claude Code pueden usar una clave, enviada como se indica arriba.