Administración de claves de API
REDA AI se puede implementar a través del canal de widget externo, lo que permite que el agente de IA impulse un chatbot en tu sitio web o aplicación externa. Para proteger este canal e impedir el uso no autorizado de tu agente, cada agente de widget externo requiere una clave de API única. Este artículo explica cómo generar, administrar, revocar y proteger las claves de API.
Descripción de las claves de API
Una clave de API es un token largo y criptográficamente seguro que autentica las solicitudes de tu sitio web o aplicación externa hacia tu agente de REDA AI. La clave cumple dos propósitos fundamentales:
- Autenticación: Comprueba que las solicitudes provienen de tu aplicación autorizada y no de un tercero malintencionado.
- Límite de tasa y gestión de cuotas: Permite que REDA AI haga seguimiento del uso por agente de widget externo y aplique límites de tasa para prevenir el abuso.
Cada agente de widget externo obtiene una clave de API. Si tienes varias implementaciones de widget externo, puedes tener varias claves de API (una por agente).
Generar una clave de API
Las claves de API se generan directamente en el registro de la Definición de agente para los agentes de widget externo.
- Abre la aplicación REDA AI — Haz clic en el Iniciador de aplicaciones y selecciona REDA AI.
- Ve a las Definiciones de agentes — En la aplicación REDA AI, haz clic en la pestaña Agentes para ver todos los agentes. Busca y haz clic en el agente configurado para el widget externo.
- Desplázate hasta la sección de la clave de API — En el registro de la Definición de agente, busca la sección Clave de API externa (por lo general, cerca del final del formulario). Inicialmente, esta sección muestra "No se ha generado ninguna clave de API".
- Haz clic en "Generar clave de API" — Se genera una nueva clave de API y se muestra en un campo de texto. La clave se muestra completa solo una vez, en el momento de la generación.
- Copia la clave de inmediato — Copia la clave completa y pégala en un lugar seguro (administrador de contraseñas, documento seguro, variable de entorno). La clave se muestra solo una vez: una vez que sales de esta página, no se puede recuperar de nuevo.
- Guarda la Definición de agente — Haz clic en Guardar para finalizar la generación de la clave.
Uso de tu clave de API
Insertar el widget externo
Una vez que tengas tu clave de API, pásala al script de inserción del widget externo junto con la URL del endpoint de tu organización. La clave va en el atributo data-api-key del código de inserción. Consulta Configuración del widget externo para ver el fragmento de inserción completo y todos los atributos de configuración disponibles.
Reemplaza los valores de marcador de posición por la clave de API que generaste y copiaste de tu Definición de agente, y por la URL del endpoint de tu organización. El widget los usa para autenticar las solicitudes a tu agente de REDA AI.
Controlar los orígenes permitidos
Para evitar que tu clave de API se use en sitios web no autorizados, utiliza el campo Orígenes permitidos en la Definición de agente. Este campo contiene una lista de orígenes de dominio separados por comas (p. ej., https://www.example.com, https://app.example.com).
Cuando llega una solicitud con tu clave de API desde un dominio que no está en la lista de Orígenes permitidos, se rechaza. Esto protege contra lo siguiente:
- Filtración de la clave: Si tu clave queda expuesta accidentalmente en el código fuente o en un repositorio público, un atacante solo podría usarla desde los dominios que hayas permitido explícitamente.
- Ataques entre sitios: Aunque un atacante inserte tu código de widget en su propio sitio, el servicio de REDA AI rechazará la solicitud porque el dominio de origen no está en la lista de permitidos.
Configurar los orígenes permitidos
- Abre la Definición de agente de tu agente de widget externo.
- Busca el campo Orígenes permitidos (o "Allowed Origins" en la interfaz).
- Introduce una lista de dominios permitidos separados por comas, incluido el protocolo (p. ej.,
https://www.example.com, https://support.example.com). - Guarda el registro. Los cambios surten efecto de inmediato.
http://localhost:3000) a tus Orígenes permitidos. Elimínalos antes de implementar en producción.Límites de tasa y protección de créditos
La Definición de agente incluye varios campos para controlar el uso de la API y protegerte contra costos descontrolados o abusos:
| Configuración | Propósito | Ejemplo |
|---|---|---|
| Rate Limit Per Hour | Número máximo de solicitudes de API por hora. Las solicitudes que superen este límite se limitan (reciben una respuesta 429 Too Many Requests). | 1000 solicitudes/hora |
| Rate Limit Per Session | Número máximo de mensajes por sesión de conversación individual. Impide que un solo usuario envíe mensajes ilimitados y consuma demasiados créditos. | 50 mensajes por sesión |
| External Daily Credit Cap | Créditos máximos que puede consumir el widget externo en un solo día. Una vez alcanzado el tope, el agente deja de responder y devuelve un error de "tope superado". Útil para controlar los costos. | 500 créditos/día |
Configura estos límites según el tráfico que esperas y los costos que consideras aceptables. Por ejemplo, si cobras a los clientes por llamada de API, establece un Límite de tasa por hora alto y un Tope de crédito diario externo basado en tu presupuesto mensual de créditos.
Revocar y rotar claves de API
Cuándo revocar una clave
Revoca una clave de API si:
- Sospechas que la clave se ha visto comprometida o filtrada
- Quieres dejar de atender solicitudes de una implementación de widget antigua
- Estás rotando claves como parte de tu política de seguridad
- Un empleado que tenía acceso a la clave ha dejado la organización
Cómo revocar una clave
- Abre la Definición de agente del agente de widget externo.
- En la sección Clave de API externa, haz clic en el botón "Revocar clave de API".
- Aparece un cuadro de diálogo de confirmación que pregunta "¿Estás seguro?" — Haz clic en Aceptar para confirmar.
- La clave se revoca de inmediato. Todas las solicitudes futuras que usen esa clave serán rechazadas con un error de autenticación.
Rotar claves (práctica recomendada)
Sigue este proceso para rotar claves sin tiempo de inactividad:
- Genera una nueva clave de API — Haz clic en "Generar clave de API" en la Definición de agente. Copia la nueva clave.
- Actualiza tu implementación del widget — Actualiza el código de inserción en tu sitio web o aplicación para que use la nueva clave de API. Implementa el cambio en producción.
- Espera a que el tráfico migre — Da tiempo para que se borren las cachés y se actualicen las sesiones de los usuarios (normalmente unas horas). Supervisa el tráfico para confirmar que las solicitudes usan la nueva clave.
- Revoca la clave anterior — Una vez que tengas la certeza de que todo el tráfico migró a la nueva clave, vuelve a la Definición de agente y haz clic en "Revocar clave de API" para deshabilitar la anterior.
Este enfoque garantiza que tus usuarios no experimenten ninguna interrupción mientras rotas a una clave nueva y segura.
Almacenamiento y seguridad de la clave de API
Cómo se almacenan las claves
La clave en sí nunca se almacena. Lo que REDA AI guarda en la definición del agente es un hash SHA-256 unidireccional con una sal aleatoria por registro, con el formato {nonce}:{hash}. El hash se calcula sobre el ID de tu organización, un secreto del lado del servidor, la sal propia de ese registro y la clave, de modo que la misma clave generada para dos agentes produce igualmente dos valores almacenados distintos, y nada del registro puede revertirse a una clave.
La consecuencia práctica: la clave completa se muestra una sola vez, al generarla. Después no se puede recuperar desde la interfaz, ni desde el registro, ni por un administrador de Salesforce; no porque esté oculta, sino porque no está ahí. Si la pierdes, la regeneras.
Proteger tu clave de API
Trata tu clave de API con la misma seguridad que una contraseña:
- Nunca la incluyas en el control de código fuente: No incluyas la clave en GitHub, GitLab ni en ningún repositorio de código público o privado.
- Usa variables de entorno: Almacena la clave en una variable de entorno o en un administrador de secretos (AWS Secrets Manager, Azure Key Vault, etc.) en tu servidor web. El código de inserción debería leer la clave del entorno, no incluirla de forma fija en el código.
- Nunca la compartas por correo: Si necesitas compartir la clave con un colega, usa el proceso seguro de tu organización para compartir credenciales (administrador de contraseñas, mensaje cifrado, etc.).
- Supervisa el acceso: En Salesforce, verifica quién tiene acceso al registro de la Definición de agente. Usa las reglas de colaboración de Salesforce para restringir la visibilidad solo a los administradores autorizados.
- Rota con regularidad: Como práctica recomendada de seguridad, rota las claves de API periódicamente (p. ej., trimestral o anualmente) mediante el proceso descrito anteriormente.
Solución de problemas con las claves de API
El widget devuelve un error "Unauthorized" o "Invalid API Key"
Causas posibles:
- La clave es incorrecta: Verifica que hayas copiado la clave completa correctamente. Revisa que no falten caracteres ni haya espacios adicionales.
- La clave está revocada: Revisa la Definición de agente: si no se muestra ninguna clave de API, es posible que la clave se haya revocado. Genera una nueva.
- El origen no está permitido: Revisa el campo Orígenes permitidos. Es posible que el dominio que realiza la solicitud no esté en la lista de permitidos. Actualiza los Orígenes permitidos si es necesario.
- La clave caducó: Si no se muestra ninguna clave y el campo está vacío, es posible que una clave haya caducado o se haya eliminado. Genera una nueva.
El widget responde con "Rate limit exceeded"
Causas posibles:
- Se superó el límite por hora: Revisa el Límite de tasa por hora. Si tu tráfico supera este límite, auméntalo o implementa una limitación de solicitudes del lado del cliente.
- Se superó el límite por sesión: Revisa el Límite de tasa por sesión. Si los usuarios individuales alcanzan el límite, auméntalo o indícales que inicien nuevas conversaciones.
- Se superó el tope diario: Revisa el Tope de crédito diario externo. Si se alcanza este límite, no se procesa ninguna solicitud hasta el día siguiente. Aumenta el tope o recarga tus créditos.
El widget devuelve "Authentication failed"
Causas posibles:
- La clave de API del código de inserción no coincide con la clave generada en la Definición de agente.
- La clave se revocó después de la implementación.
- La Definición de agente o el agente en sí se ha eliminado o deshabilitado.
Verifica el estado de la clave y del agente, y vuelve a generar o reimplementar según sea necesario.
Preguntas frecuentes
No. Cada agente de widget externo puede tener solo una clave de API activa a la vez. Sin embargo, puedes tener varios agentes de widget externo, cada uno con su propia clave de API. Si necesitas claves separadas para diferentes implementaciones, crea agentes separados para cada implementación.
Revoca de inmediato la clave comprometida haciendo clic en "Revocar clave de API" en la Definición de agente. Luego, genera una clave nueva e implementa el código de inserción actualizado en tu sitio web. Si la clave comprometida se usó en un sitio no confiable, revisa tus registros de uso y el historial de créditos para detectar actividad sospechosa. Comunícate con el Soporte de REDA AI si necesitas ayuda para investigar el uso no autorizado.
No. Las claves de API son solo para el canal de widget externo. Slack, Teams, el correo y otros canales de REDA AI usan sus propios métodos de autenticación (tokens de espacio de trabajo, cuentas de servicio, etc.) y no requieren claves de API.
El widget rechazará las nuevas solicitudes con un código de estado HTTP "429 Too Many Requests". El usuario final verá en el widget un mensaje que indica que el agente no está disponible temporalmente. Los límites de tasa se restablecen en el siguiente límite de hora o de sesión, según cuál se haya superado. Si alcanzas los límites de forma constante, aumenta los valores de Límite de tasa por hora o Límite de tasa por sesión en la Definición de agente.