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.
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 encabezadoAuthorization:
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, salvoGET /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.
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 /businessesnecesitabusinesses:createyPOST /usersnecesitausers:create. Solo las claves de plataforma pueden tener estos dos, y una clave nueva los recibe solo si usted pasa--create-businesseso--create-users.GET /businessesnecesitabusiness:read. El comando rechaza los permisos de socio, porque una clave del anfitrión no tiene un socio en cuyo nombre actuar.
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.
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:
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 conPUBLIC_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.