Saltar al contenido principal
Cada solicitud necesita una clave. Una clave de API del panel actúa sobre un solo negocio, y una clave de plataforma sobre varios. Los propietarios y administradores crean y revocan las claves de API en el panel. Las claves de API, pero no las de plataforma, también conectan asistentes de IA a través del servidor MCP.

Cree una clave

1

Abra Claves de API

Vaya a Configuración > Claves de API. Solo los propietarios y administradores ven esta página.
2

Asigne un nombre a la clave y elija su acceso

Use un nombre que pueda reconocer más adelante, como Zapier. Seleccione solo los permisos que necesita la herramienta.
3

Copie la clave

LobbyStack muestra la clave completa una sola vez. Guárdela en su herramienta o en un gestor de contraseñas. LobbyStack solo conserva un hash, así que nadie puede volver a mostrar la clave.
Las claves tienen la forma lsk_1a2b3c4d_ seguido de 32 caracteres aleatorios. El panel muestra cada clave por su nombre, con quién la creó y cuándo se usó por última vez.

Envíe la clave

Ponga la clave en el encabezado Authorization:
Una clave ausente, desconocida o revocada devuelve 401 con el código unauthorized.

Pruebe una clave

GET /me funciona con cualquier clave válida, sin importar sus permisos. Devuelve la clave y su negocio, de modo que una integración puede comprobar la conexión antes de necesitar un permiso concreto:

Permisos

Cada endpoint, salvo GET /me, requiere un permiso (scope). Una clave sin ese permiso recibe 403 con el código insufficient_scope, y el mensaje indica el permiso que falta. Para suscribir un endpoint a un evento o cambiar su URL, su clave también necesita el permiso de lectura de ese evento. Por ejemplo, call.completed requiere calls:read, y la tabla de eventos de la página Webhooks indica los demás.

Claves de plataforma

Una clave de plataforma (lsp_...) incorpora y gestiona muchos negocios, mientras que una clave de API actúa sobre uno solo. Puede usarlas para configurar los negocios que atiende, por ejemplo con lobbystack onboard. Un socio crea sus propias claves de plataforma en su consola de socios. El anfitrión, es decir, quien opera el despliegue, define las demás en PLATFORM_API_KEYS.

Cree la clave de plataforma de un socio

1

Abra Claves de API

En la consola de socios, vaya a Claves de API. Solo los propietarios y administradores del socio pueden crear y revocar claves.
2

Ponga nombre a la clave y elija su acceso

Seleccione solo los permisos que necesita la herramienta. POST /businesses necesita businesses:create, y POST /users necesita users:create.
3

Copie la clave

La consola muestra la clave completa una sola vez. LobbyStack guarda solo un hash, así que nadie puede volver a mostrarla.
La clave de plataforma de un socio actúa en nombre del socio, así que sigue funcionando cuando la persona que la creó deja el equipo. Sus alcances de facturación son la excepción: consulte Endpoints de socio. Llega a los negocios activos del socio, incluidos los que se crearon desde la consola, y a ningún otro. Con los permisos de socio, también gestiona al socio mismo con los endpoints de socio. No puede iniciar un pago de Polar para un negocio, fijar un plan gestionado ni crear un enlace de reclamación. Tampoco puede consultar ni cambiar las preferencias de alertas, porque esas acciones se hacen en nombre de una persona. Con la clave de plataforma de un socio, POST /businesses crea un negocio del socio, todavía sin propietario. Indique el propietario en owner_email, y el socio le envía por correo una invitación para iniciar sesión en su panel. access_level define lo que puede usar el equipo del negocio: full, el valor predeterminado, o activity. template_id parte de una de las plantillas del socio y también necesita partner:read. package_id le vende al negocio uno de los paquetes del socio y también necesita partner.businesses:write. Sin ese alcance, la solicitud devuelve 403 con el código insufficient_scope. Las claves de plataforma de un socio pueden crear 30 negocios por hora en total. Las invitaciones que envía con POST /team/invitations y POST /users llegan del socio y llevan a su panel. Omita owner_email para un negocio que el socio gestiona por sí mismo. Nadie recibe una invitación, y una clave no puede invitar a un propietario más tarde, así que el negocio no se puede entregar. package_id devuelve entonces 400, porque el pago se abre desde la invitación del propietario. Con phone_numbers:manage y phone_numbers:purchase, la clave de un socio busca, reserva y reemplaza números en su propio nombre. En un despliegue que factura los niveles, esto necesita un nivel de pago, y Free devuelve 409. Una clave solo puede reservar una oferta que ella misma buscó, y nunca recibe una oferta de prueba. Las claves del socio comparten 20 búsquedas cada 10 minutos. Los enlaces que devuelve la API para el negocio de un socio, como la etiqueta de script de un widget o un enlace para conectar un calendario, también llevan al panel del socio.

Endpoints de socio

Los endpoints bajo /partner hacen lo que hace la consola de socios. Leen al socio, gestionan sus demos, paquetes, marca, dominio, plantillas y equipo, y también su cuenta de Stripe y su nivel. Solo la clave de un socio puede llamarlos, sin el encabezado LobbyStack-Business. Una clave API o una clave del anfitrión recibe 403 con el código forbidden. Una clave actúa con los derechos de un administrador, así que nunca cambia a un propietario. Invitar a un propietario, cambiar el rol de un propietario o quitar a uno devuelve 403: hágalo en la consola. Solo los propietarios pueden conceder partner.billing:read y partner.billing:write, porque dan acceso a lo que solo los propietarios ven en la consola. partner.billing:write incluye lo que permite partner.billing:read. Los alcances de facturación funcionan mientras el propietario que los concedió siga siendo propietario: el que creó la clave con ellos, o el que la actualizó por última vez con ellos. Cuando esa persona pasa a administrador o deja el equipo, las solicitudes de facturación de la clave devuelven 409 con el código key_owner_inactive, y sus demás alcances siguen funcionando. POST /partner/billing/checkout emite el pago del nivel a nombre de ese propietario. POST /partner/team/invitations exige un Idempotency-Key, y POST /partner/packages, POST /partner/templates y POST /partner/billing/checkout aceptan uno. POST /partner/demos y POST /partner/demos/{demo_id}/rotate lo ignoran, así LobbyStack nunca guarda una copia del enlace de una demo. Tras un error de red, consulte GET /partner/demos antes de reintentar. PATCH /partner/brand acepta un logotipo o un favicon en base64, como los sube la consola.

Cree una clave del anfitrión

El panel no tiene una página para las claves del anfitrión. En un despliegue autoalojado, pnpm platform-key:create escribe una clave nueva en .platform-keys/<prefix>.json e imprime su entrada para PLATFORM_API_KEYS. Cada entrada define:
  • El grupo al que pertenece la clave (group; pase --group). Las claves de un mismo grupo llegan a los mismos negocios.
  • La cuenta verificada de LobbyStack en cuyo nombre actúa la clave (owner_email), que es la propietaria de los negocios que crea.
  • Si la clave llega a todos los negocios ("access": "all"; pase --access all) o, de forma predeterminada, solo a los que incorporaron las claves de su grupo ("access": "group").
  • Sus permisos. Salvo que usted indique algunos, una clave nueva recibe los permisos que puede tener una clave API. POST /businesses necesita businesses:create y POST /users necesita users:create. Solo las claves de plataforma pueden tener estos dos, y una clave nueva los recibe solo si usted pasa --create-businesses o --create-users. GET /businesses necesita business:read. El comando rechaza los permisos de socio, porque una clave del anfitrión no tiene un socio en cuyo nombre actuar.
Las entradas más antiguas llaman partner al grupo y pueden indicar "access": "partner". Ambos siguen funcionando, y la clave llega a los mismos negocios. Para actualizar una, cambie partner por group y "access": "partner" por "access": "group". Actualice primero el admin: las versiones anteriores rechazan group. El admin rechaza una entrada que define a la vez partner y group, y con ella todas las claves de PLATFORM_API_KEYS.
Una clave con "access": "all" actúa en nombre de la cuenta de su owner_email en todos los negocios del despliegue, sin formar parte de ningún equipo, y puede leerlos y cambiarlos todos. Esa clave, y esa cuenta con su contraseña, sus sesiones y su bandeja de entrada, son credenciales raíz. Déselas a la menor cantidad de personas posible, proteja la contraseña de la cuenta como la de la base de datos y quite la entrada de la clave de PLATFORM_API_KEYS si alguna se filtra. pnpm platform-key:create --access all muestra la misma advertencia.
Cuando el admin se reinicia sin la entrada de una clave en PLATFORM_API_KEYS, las solicitudes con esa clave fallan y LobbyStack desactiva los endpoints de webhook que creó la clave. Para conservar uno, vuelva a activarlo con otra de sus claves de plataforma.

Use una clave de plataforma

POST /businesses crea un negocio. GET /businesses lista los que incorporó el grupo de la clave o, para la clave de plataforma de un socio, todos los negocios del socio. Las demás solicitudes indican su negocio en el encabezado LobbyStack-Business:
Sin ese encabezado, la solicitud devuelve 400 con el código business_required. Un negocio al que la clave no puede llegar devuelve 404. GET /me funciona sin el encabezado y muestra el grupo y el alcance de la clave en platform. platform.reach vale group para una clave con acceso de grupo y all para una clave que llega a todos los negocios. La API v1 conserva también los nombres anteriores: platform.partner repite platform.group, y platform.access repite platform.reach, pero vale partner para el acceso de grupo. Para la clave de plataforma de un socio, platform.partner_id indica el socio, que también es el grupo de la clave. Vale null para las claves del anfitrión. POST /team/claim-link entrega un negocio a su propietario. Cuando lo acepta, una clave con acceso de grupo ya no llega al negocio, mientras que una clave con acceso a todos los negocios sigue llegando. En ambos casos, GET /businesses deja de listarlo. LobbyStack también desactiva los endpoints de webhook del negocio que creó una clave de plataforma, la cuenta que envió el enlace o las claves API de esa cuenta. El negocio de un socio se queda con ese socio, así que POST /team/claim-link devuelve 409 para él. Solo el socio puede cedérselo a su propietario. Solo una cuenta de LobbyStack verificada puede aceptar un enlace de reclamación, y la página del enlace permite que un propietario sin cuenta se registre primero. Para invitarlo antes, POST /users envía a la dirección un enlace de registro, o un enlace para iniciar sesión si la dirección ya tiene una cuenta. Nunca crea una cuenta: el propietario se registra con su propia contraseña o con Google. La respuesta es la misma en los dos casos, así que usted no puede saber quién tiene una cuenta. Una clave de plataforma puede invitar a 50 direcciones al día.

Actualice una clave

En Configuración > Claves de API, haga clic en Actualizar junto a la clave para cambiar su nombre o sus permisos, y luego en Guardar. La clave sigue siendo la misma, y las solicitudes que la usen reciben los nuevos permisos de inmediato. No puede actualizar una clave revocada. En la página Claves de API de la consola de socios, solo los propietarios pueden actualizar una clave de plataforma con acceso a la facturación.

Revoque una clave

En Configuración > Claves de API, haga clic en Revocar junto a la clave. Las solicitudes que la usen fallan de inmediato, y no se puede deshacer. Cree una nueva clave si todavía necesita acceso. LobbyStack también desactiva los endpoints de webhook que creó la clave. Para conservar uno, vuelva a activarlo en Configuración > Webhooks. Para revocar una clave de plataforma de un socio, haga clic en Revocar junto a ella en la página Claves de API de la consola de socios. Las solicitudes que la usen fallan de inmediato. LobbyStack desactiva los endpoints de webhook que creó en todos los negocios, y revoca las invitaciones que envió, al equipo de un negocio o al del socio, y que nadie ha aceptado todavía. Los propietarios a los que invitó al crear su negocio aún pueden aceptar.

Límites de frecuencia

Cada clave puede hacer 120 solicitudes por minuto. Las implementaciones autoalojadas pueden cambiar este valor con PUBLIC_API_RATE_LIMIT_PER_MINUTE. La ventana se reinicia al comienzo de cada minuto. Cada respuesta incluye estos encabezados: Al superar el límite, la API devuelve 429 con el código rate_limited y un encabezado Retry-After con los segundos que debe esperar.

Proteja sus claves

  • Use una clave por herramienta para poder revocar una sin afectar a las demás.
  • Dé a cada clave los permisos mínimos que funcionen.
  • Nunca ponga una clave en código del navegador ni en una aplicación móvil. Llame a la API desde un servidor.
  • LobbyStack registra cada solicitud con el ID de la clave, nunca con la clave en sí, y anota los cambios hechos con una clave en el registro de auditoría del negocio.