Autenticación de la API REST

La API REST de LeadsBase está expuesta en https://api.leadsbase.es/v1/ y usa autenticación por bearer token. Hay dos tipos de credenciales: API keys (para tu propio uso) y OAuth client credentials (para apps que quieren autenticar a múltiples usuarios de LeadsBase).

1. API keys

Para uso interno (tu CRM, tu data warehouse, scripts ad-hoc) genera una API key como se describe en crear API key. Todas las requests incluyen:

Authorization: Bearer lb_live_xxxxxxxxxxxxxxxxxxxxxxxx
Accept: application/json
User-Agent: mi-aplicacion/1.2.3

Las keys empiezan por:

• lb_live_ — entorno de producción.
• lb_test_ — entorno sandbox con datos ficticios.

Usa siempre sandbox para desarrollo. Las requests en lb_test_ no consumen créditos.

2. Scopes

Cada API key tiene scopes asignados al crearla. La granularidad es:

• Lectura: empresas:read, lists:read, webhooks:read.
• Escritura: lists:write, webhooks:write, imports:create.
• Enriquecimiento: empresas:enrich.
• Admin: admin:billing, admin:members, admin:keys.

Si una request requiere un scope que tu key no tiene, devolvemos 403 Forbidden con error_code: "missing_scope".

3. OAuth 2.0 client credentials

Si construyes una app que quieres listar en nuestro marketplace, usa el flujo OAuth. Pide credenciales en Ajustes → Apps OAuth → Nueva app. Recibes:

• client_id: identificador público.
• client_secret: secret confidencial.
• redirect_uri: tu callback URL.

El flujo es estándar OAuth 2.1 (PKCE recomendado):

1. Usuario clica "Conectar con LeadsBase" en tu app.
2. Rediriges a https://leadsbase.es/oauth/authorize con client_id, scope, code_challenge.
3. Usuario aprueba en LeadsBase y vuelve a tu redirect_uri con un code.
4. Tu backend cambia code + verifier por un access_token en POST /oauth/token.
5. Usas el access_token en cabecera Authorization.

Los access_token duran 1 hora y se renuevan con refresh_token (válido 90 días).

4. Rate limits básicos

Todas las requests cuentan contra el rate limit del workspace:

• Starter: 30 req/min.
• Pro: 300 req/min.
• Business: 1500 req/min.
• Enterprise: custom.

Cabeceras de respuesta:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
X-RateLimit-Reset: 1747824000

Cuando excedes el límite devolvemos 429 Too Many Requests con Retry-After. Detalle en rate limits.

5. Versionado

La API usa versionado por URL. La versión actual es v1. Cuando publiquemos v2, mantendremos v1 operativa al menos 24 meses con avisos de deprecación.

Las breaking changes se anuncian en el changelog público con 90 días de antelación mínimo.

6. Idempotencia

Los métodos POST que crean recursos aceptan cabecera Idempotency-Key:

curl -X POST https://api.leadsbase.es/v1/imports \
  -H 'Authorization: Bearer lb_live_...' \
  -H 'Idempotency-Key: 8f4e3a2b-d5c6-4a1b-9e8d-1c2b3a4d5e6f' \
  -d @import.json

Si reintentas con la misma clave en menos de 24h, devolvemos la misma respuesta sin duplicar el recurso. Muy útil para evitar imports dobles tras un timeout.

7. CORS y uso desde navegador

No exponer API keys en frontend. La API tiene CORS habilitado solo para el dashboard oficial. Si necesitas que un SPA hable con LeadsBase, monta un proxy en tu backend que añada la Authorization.

8. SDKs oficiales

Mantenemos SDKs en:

• Python: pip install leadsbase (cliente async con httpx).
• Node.js: npm install @leadsbase/sdk (TypeScript first).
• PHP: composer require leadsbase/sdk-php.
• Go: go get github.com/leadsbase/leadsbase-go.

Todos manejan retries, rate limits y paginación automáticamente.

Si construyes integraciones para terceros, lee también el acuerdo de marketplace antes de publicar.

Para entender los límites de tu plan, ver rate limits. Para diagnosticar respuestas erróneas, errores comunes.