> For the complete documentation index, see [llms.txt](https://boundaryai.gitbook.io/boundaryai-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://boundaryai.gitbook.io/boundaryai-docs/boundaryai-docs-es/api-y-webhooks/authentication.md). # Autenticación y claves de API Claves de API, ámbitos de permisos, entornos y límites de tasa. Cada llamada a la API se autentica con una **clave de API** pasada como token portador: ``` Authorization: Bearer inpk_live_... ``` No hay cookies de sesión en la API: una clave, un encabezado. Las funciones del panel (crear encuestas, gestionar miembros, configuración de la organización) no son accesibles con una clave de API por diseño. El único lugar en el que existe acceso basado en inicio de sesión es el flujo de conexión del asistente de IA, que usa OAuth en lugar de una clave; consulta [Conectar asistentes de IA](/boundaryai-docs/boundaryai-docs-es/api-y-webhooks/mcp.md). *** ### Creación y gestión de claves Las claves se encuentran en el panel, en **Integraciones → Herramientas de desarrollador → Claves de API** (solo administradores). Cada clave tiene: * Una **etiqueta**, para que puedas distinguir la sincronización de tu CRM de la exportación de tu almacén de datos. * Un **entorno**: `inpk_live_*` para tráfico de producción, `inpk_test_*` para integraciones de preproducción. Se comportan de forma idéntica; la separación existe para que puedas revocar la preproducción sin tocar producción. A las claves de prueba nunca se les cobra uso. * Una **ámbito de permisos** (abajo). * Una **límite de tasa por clave**, 60 solicitudes/minuto por defecto, ajustable entre 1 y 300 al crearla o después. * **Estadísticas de uso por clave**, incluidos los códigos de estado reales de las respuestas, para que puedas detectar una integración fallida desde el panel. El secreto se muestra **una sola vez** al crearlo. Guárdalo como una contraseña; gíralo desde la misma pantalla si se filtra o cuando un compañero con acceso se vaya. *** ### Ámbitos de permiso Limita lo que puede hacer cada integración; no le des a cada sistema una `all` clave. | Ámbito | Lo que permite | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `push` | Enviar comentarios a las fuentes existentes, y todo lo que implica push: estado masivo, carga de archivos, listado y borrado de comentarios, lecturas de análisis. | | `create` | Todo `push` puede, además de crear y publicar fuentes con sus campos dentro de grupos de comentarios existentes. | | `send` | Activar correos electrónicos de invitación a encuestas ([Enviar invitaciones](/boundaryai-docs/boundaryai-docs-es/api-y-webhooks/sending-invites.md)). A propósito, se mantiene separado: enviar correos a personas es algo más importante que enviar datos. | | `mcp_read` | Acceso de solo lectura para el extremo MCP, de modo que un asistente de IA pueda consultar analíticas pero nunca escribir. Consulta [Conectar asistentes de IA](/boundaryai-docs/boundaryai-docs-es/api-y-webhooks/mcp.md). | | `all` | Todo lo anterior, además de crear grupos de comentarios (`POST /feedback_groups/create`), algo que ningún ámbito más restringido puede hacer. | Cada operación de escritura en la referencia de la API indica el ámbito que requiere. Una llamada fuera del ámbito de la clave devuelve **403** con el código `INSUFFICIENT_PERMISSION`. {% hint style="info" %} `send` también está condicionada a un **dominio de envío verificado**: los envíos de la API nunca usan el remitente compartido de BAI Analytics, por lo que el volumen automatizado se ejecuta con tu propia reputación de envío. Consulta [Enviar invitaciones](/boundaryai-docs/boundaryai-docs-es/incorporacion-de-sus-comentarios/surveys/managing-surveys.md#sending-invites). {% endhint %} {% hint style="info" %} `mcp_read` las claves están **vinculadas a la persona que las creó**. En cada solicitud MCP, la plataforma vuelve a comprobar que esta persona siga teniendo una cuenta activa y siga siendo miembro de la organización; si no, la clave deja de funcionar de inmediato (403 `MCP_KEY_UNBOUND`) y aparece como detenida en el panel. Las claves de integración (`push`, `create`, `send`, `all`) son claves de la organización y sobreviven a quien las creó, así que un pipeline ETL sigue ejecutándose después de que se marche el ingeniero que lo configuró. {% endhint %} *** ### Introspección: `GET /me` Una integración puede descubrir sus propias capacidades sin acceso al panel: ```bash curl https://boundaryai-ingest-279197672085.europe-west9.run.app/api/input/me \\ -H "Authorization: Bearer $BAI_API_KEY" ``` La respuesta incluye el nombre, el entorno y los permisos de la clave, el id de la organización y `org_name` (útil como etiqueta de una conexión guardada), el **límites de tasa efectivos**, el estado de uso de la organización en `créditos`, y los **tipos de eventos de webhook** disponibles para suscripción. No cuesta nada, lo que también lo convierte en el objetivo adecuado para pruebas de conexión. *** ### Límites de velocidad Valores predeterminados: **60 solicitudes/minuto por clave**, **300 solicitudes/minuto por organización**, y 600 por minuto por dirección IP. Las ventanas son ventanas fijas de 60 segundos ancladas a la primera solicitud: una solicitud rechazada con 429 no extiende la espera, así que `Retry-After` es exacto. Los números de tu clave están en `GET /me`; el límite por clave puede aumentarse hasta 300 cuando la clave se crea o se edita. Cuando alcanzas un límite, la API devuelve **429** con un `Retry-After` encabezado, y cada respuesta lleva `X-RateLimit-Limit`, `X-RateLimit-Remaining`, y `X-RateLimit-Reset`. Reduce la velocidad e inténtalo de nuevo; para volumen sostenido, prefiere los endpoints masivos (una llamada para miles de elementos) frente a las llamadas por elemento. *** ### Sobre de respuesta Hoy, las respuestas 2xx llevan la carga útil directamente, como se muestra en todos los ejemplos de la referencia, junto con `Deprecation` y `Sunset` encabezados. Esos encabezados anuncian solo una cosa: después de la fecha de retirada, las cargas útiles correctas se envolverán como `{"data": {...}}`, tal como ya declaran los esquemas. No se está descontinuando ningún endpoint. Los errores siempre son `{"error": {"code": "...", "message": "..."}}` con un opcional `details` objeto. *** ### Buenas prácticas * **Una clave por integración.** Revocar un sistema comprometido no debería dejar fuera a los demás. * **Limita el ámbito.** Una sincronización de CRM necesita `push`, no `all`. * **Usa `Idempotency-Key` en escrituras.** Cualquier envío push puede reintentarse de forma segura dentro de las 24 horas. * **Rota las claves cuando haya cambios de personal.** La misma política que las contraseñas.