Cómo crear tu primera API key

Si quieres integrar LeadsBase con tu CRM, tu data warehouse o un workflow propio, necesitas una API key. Cada key se asocia a un workspace y a un usuario humano responsable, y se revoca con un solo clic.

1. Accede al panel de desarrolladores

En el dashboard, ve a Ajustes → API keys. Verás dos pestañas: Keys activas y Logs de uso. Necesitas rol owner o developer para crear nuevas keys.

2. Crea una key con scope mínimo

Pulsa Nueva API key y rellena:

• Nombre: descriptivo (ej. "HubSpot prod" o "Script enrichment").
• Scope: solo los permisos que necesites. El principio de mínimo privilegio aplica.
• Expiración: opcional. Recomendado 90 días para keys de scripts ad-hoc.
• IP allowlist: opcional. Recomendado para keys de servidor.

Los scopes disponibles son:

• empresas:read — lectura del catálogo de empresas.
• empresas:enrich — enriquecimiento puntual con créditos.
• lists:write — crear y actualizar listas guardadas.
• webhooks:manage — registrar y eliminar webhooks.
• admin:* — solo para usuarios owner; permite gestionar miembros del workspace.

3. Guarda la key inmediatamente

Cuando confirmas la creación, la API key aparece una sola vez. Internamente guardamos solo el hash SHA-256, no el valor original. Si la pierdes, tendrás que generar una nueva.

Recomendaciones de almacenamiento:

• En servidor: variable de entorno (LEADSBASE_API_KEY) o secret manager (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault).
• En cliente: nunca la incluyas en código frontend. Usa un proxy backend.
• En scripts personales: archivo .env excluido por .gitignore.

4. Primera request autenticada

Todas las requests usan header Authorization: Bearer <key>. Por ejemplo, para buscar empresas en Madrid del CNAE 6201:

curl -X GET 'https://api.leadsbase.es/v1/empresas?provincia=madrid&cnae=6201' \
  -H 'Authorization: Bearer lb_live_xxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Accept: application/json'

Respuesta esperada (resumida):

{
  "count": 4821,
  "page": 1,
  "results": [
    {
      "cif": "B12345678",
      "razon_social": "Ejemplo Tech SL",
      "cnae": "6201",
      "empleados": "10-49"
    }
  ]
}

5. Monitoriza el uso

En la pestaña Logs de uso verás cada request con timestamp, endpoint, status code y duración. Si una key se compromete, púlsala Revocar y queda inactiva en menos de un segundo.

Para detalles de límites, consulta rate limits y cuotas. Si recibes errores 401 o 403, mira los errores comunes de la API.