Autenticación

Todas las solicitudes llevan una clave de API en la cabecera Authorization:

Authorization: Bearer lp_live_XXXXXXXX…    (clave de espacio de trabajo)
Authorization: Bearer lpp_live_XXXXXXXX…   (clave de partner)

Las claves se crean en el panel, se muestran una sola vez al crearlas y se guardan como hash SHA-256: nadie, ni siquiera soporte, puede recuperar una clave perdida. Perder una clave significa revocarla y crear otra.

Tipos de clave

• Claves de espacio de trabajo (lp_live_…): actúan dentro de un espacio de trabajo, sobre enlaces, analíticas, dominios, registro de auditoría y webhooks del espacio. Las crean los administradores del espacio en Ajustes → Claves de API.
• Claves de partner (lpp_live_…): actúan sobre la cuenta de partner, con clientes, planes, dominios, pagos, liquidaciones y webhooks de partner. Las crean los administradores del partner.

Una clave de espacio de trabajo que llame a /partner/* (o al revés) recibe un 403 forbidden: las familias de endpoints están estrictamente separadas.

Alcances

Los alcances se conceden por clave en el momento de crearla. Una solicitud necesita todos los alcances que exija su endpoint; si falta uno, la respuesta es 403 insufficient_scope indicando cuál falta.

| Alcance | Permite | |---|---| | links:read / links:write | Leer / crear, actualizar, archivar y borrar enlaces | | analytics:read | Resumen, series temporales, desgloses, enlaces destacados, exportación CSV y la vista global de clics del partner | | domains:read / domains:write | Leer / conectar y desconectar dominios | | qr:read | Generar los códigos QR de los enlaces | | workspace:read | Perfil del espacio de trabajo, límites y registro de auditoría | | webhooks:read / webhooks:write | Leer / gestionar endpoints de webhook | | partner:read | Perfil, plan y consumo del partner | | clients:read / clients:write | Leer / crear, modificar y suspender clientes | | plans:read / plans:write | Leer / gestionar los planes del partner | | payments:read | Espejo de pagos y liquidaciones |

Esa es la lista completa —quince alcances— y una clave solo puede contener nombres de ella. Los códigos QR son de solo lectura por API: generarlos requiere qr:read, y no hay alcance de escritura de QR porque no existe endpoint de mutación de QR.

Hay una combinación que despista: GET /partner/analytics/overview necesita analytics:read en la clave de partner, no partner:read. Todos los endpoints de analíticas usan el mismo alcance, sea cual sea el tipo de clave.

Dale a cada integración su propia clave con los alcances mínimos que necesite: una clave para un widget de panel se apaña con links:read + analytics:read, mientras que un script de aprovisionamiento necesita clients:write.

Restricciones por plan

El acceso a la API es una función del plan (api_access):

• para las claves de espacio de trabajo, tanto el plan del espacio como el plan de plataforma del partner deben incluir acceso a la API;
• para las claves de partner, debe incluirlo el plan de plataforma del partner.

Un plan sin acceso a la API responde 403 plan_restricted. Los espacios de trabajo en prueba, todavía sin plan, no están restringidos.

Rotación y revocación

Revocar una clave surte efecto de inmediato: la siguiente solicitud responde 401 unauthorized. Para rotar sin cortes, crea primero la clave nueva, cambia la integración y revoca después la antigua. Cada clave registra last_used_at, así que una clave vieja sin uso es fácil de detectar antes de revocarla.

Opcionalmente, una clave puede llevar fecha de caducidad: las claves caducadas se comportan exactamente igual que las revocadas.

Buenas prácticas

• Las claves son secretos: guárdalas en un gestor de secretos y nunca en código de cliente, repositorios o logs.
• Una clave por integración: revocar una no rompe las demás, y el registro de auditoría atribuye cada cambio a la clave que lo hizo.