El conector personalizado de Copilot studio devuelve 401 no autorizado: solución

Al crear un conector personalizado en Copilot Studio, es posible que aparezca un error 401 No autorizado cuando el conector intenta llamar a una API externa. Este error significa que la API rechazó la solicitud porque no se proporcionaron credenciales de autenticación válidas. La causa raíz casi siempre es una discrepancia entre el método de autenticación configurado en el conector y lo que espera la API. Este artículo explica por qué se produce el error 401 y proporciona soluciones paso a paso para los escenarios de autenticación más comunes.

Por qué se produce el error 401 No autorizado

El error 401 No autorizado es un código de estado HTTP que significa que el servidor de la API recibió la solicitud, pero no la procesará porque la autenticación falta, no es válida o ha expirado. En los conectores personalizados de Copilot Studio, esto ocurre cuando la configuración de autenticación no coincide con lo que espera la API externa.

Existen tres causas raíz comunes:

Tipo de autenticación incorrecto

Cada API admite un método de autenticación específico. Si selecciona Clave de API en el conector pero la API espera OAuth 2.0, el servidor rechazará la solicitud con un error 401. El conector debe usar el método exacto definido en la documentación de la API.

Credenciales o token incorrectos

Incluso con el tipo de autenticación correcto, las credenciales reales deben ser válidas. Una clave de API puede haber expirado, un token de OAuth puede haber sido revocado o una combinación de nombre de usuario y contraseña puede ser incorrecta. Copilot Studio no valida las credenciales hasta que se prueba el conector o se usa en una conversación.

Parámetros faltantes o con nombre incorrecto

Para la autenticación con clave de API, el conector debe enviar la clave en el encabezado o parámetro de consulta correcto. Por ejemplo, si la API espera la clave en un encabezado llamado X-API-Key pero el conector la envía en Authorization, la API devuelve 401. Lo mismo se aplica a los ámbitos de OAuth, los tipos de concesión y los puntos de conexión de token.

Pasos para solucionar el error 401 No autorizado

Siga estos pasos en orden. Cada paso aborda una de las causas raíz anteriores.

Paso 1: Verificar los requisitos de autenticación de la API

1. Abra la documentación de la API
   Localice la documentación oficial de la API a la que se está conectando. Busque la sección de autenticación. Anote el tipo de autenticación exacto: clave de API, OAuth 2.0, autenticación básica u otro método.
2. Registre los nombres exactos de los parámetros
   Para la clave de API, anote el nombre del encabezado o el nombre del parámetro de consulta. Para OAuth 2.0, anote la URL de autorización, la URL del token, el ID de cliente, el secreto de cliente, los ámbitos y el tipo de concesión. Para la autenticación básica, tenga en cuenta que la API espera una cadena username:password codificada en Base64 enviada en el encabezado Authorization.

Paso 2: Revisar la configuración de autenticación del conector

1. Inicie sesión en Copilot Studio
   Vaya a https://copilotstudio.microsoft.com y abra su copiloto.
2. Vaya a Conectores personalizados
   Seleccione Configuración en la esquina superior derecha y, a continuación, elija Conectores personalizados. Busque el conector que devuelve el error 401 y haga clic en Editar.
3. Revise la pestaña Autenticación
   Haga clic en la pestaña Autenticación. Compare el tipo de autenticación seleccionado con la documentación de la API. Si no coinciden, cambie el tipo de autenticación al correcto.
4. Actualice los parámetros
   Para la clave de API, escriba el nombre exacto del encabezado o del parámetro de consulta de la documentación. Para OAuth 2.0, escriba la URL de autorización, la URL del token, el ID de cliente, el secreto de cliente y los ámbitos exactamente como se especifica. Para la autenticación básica, escriba el nombre de usuario y la contraseña.

Paso 3: Probar el conector con una operación simple

1. Cree una operación de prueba
   En el editor del conector, vaya a la pestaña Definición y agregue una nueva operación que realice una solicitud GET simple a un punto de conexión público de la API que requiera datos mínimos.
2. Haga clic en Probar operación
   Seleccione la operación de prueba y haga clic en Probar operación en la barra de herramientas. Aparecerá un cuadro de diálogo que muestra la solicitud y la respuesta. Si la respuesta es 200 OK, la autenticación está configurada correctamente. Si sigue viendo 401, continúe con el paso siguiente.

Paso 4: Validar las credenciales fuera de Copilot Studio

1. Use una herramienta como Postman o curl
   Envíe la misma solicitud a la API con el mismo método de autenticación y las mismas credenciales. Si obtiene una respuesta 200, las credenciales son válidas y el problema está en la configuración del conector. Si obtiene 401, las credenciales en sí son incorrectas o han expirado.
2. Renueve o reemplace las credenciales
   Si las credenciales no son válidas, genere una nueva clave de API, actualice el token de OAuth o restablezca la contraseña. A continuación, actualice el conector con las nuevas credenciales.

Paso 5: Comprobar las restricciones de directiva o ámbito

1. Revise las directivas de acceso a la API
   Algunas API restringen el acceso según la dirección IP, el agente de usuario o la frecuencia de las solicitudes. Asegúrese de que las solicitudes del conector de Copilot Studio no estén bloqueadas por dichas directivas.
2. Verifique los ámbitos de OAuth
   Para OAuth 2.0, el token debe incluir los ámbitos requeridos por el punto de conexión de la API. Agregue los ámbitos faltantes en la pestaña Autenticación del conector y vuelva a generar el token.

Si el error 401 persiste después de la solución principal

A veces, el error continúa incluso después de verificar el tipo de autenticación y las credenciales. Los siguientes problemas son menos comunes, pero igualmente importantes de comprobar.

El conector personalizado usa una referencia de conexión compartida

Si el conector usa una referencia de conexión que se comparte entre varios entornos, las credenciales almacenadas en esa referencia pueden estar desactualizadas. Vaya al Centro de administración de Power Platform, busque la referencia de conexión y actualice las credenciales. Después, vuelva a probar el conector en Copilot Studio.

La puerta de enlace de API o el proxy agrega autenticación

Algunas API se encuentran detrás de una puerta de enlace que requiere su propia autenticación, como Azure API Management. En ese caso, el conector personalizado debe incluir tanto la autenticación de la puerta de enlace como la autenticación de la API de back-end. Configure el conector para enviar las credenciales de la puerta de enlace en el encabezado de la solicitud y las credenciales del back-end en el cuerpo o en un encabezado independiente.

El token de OAuth expira durante una conversación

Si el conector funciona durante las pruebas pero devuelve 401 después de unos minutos en un copiloto activo, es posible que el token de OAuth haya expirado. Configure el conector para usar un token de actualización si la API lo admite. En la pestaña Autenticación, habilite la opción de token de actualización y proporcione la URL del token de actualización y los parámetros necesarios.

Métodos de autenticación de conectores personalizados de Copilot Studio: comparación

Elemento	Clave de API	OAuth 2.0	Autenticación básica
Descripción	Una clave estática enviada en un encabezado o parámetro de consulta	Delegación basada en tokens mediante puntos de conexión de autorización y token	Nombre de usuario y contraseña enviados como una cadena codificada en Base64
Caso de uso común	API públicas simples, servicios meteorológicos, pasarelas de pago	Microsoft Graph, Salesforce, API de Google, API de redes sociales	API heredadas, API corporativas internas con seguridad básica
Expiración de credenciales	A menudo estáticas, pero pueden rotarse	El token expira en minutos u horas; el token de actualización puede extenderlo	Estáticas hasta que se cambia la contraseña
Configuración en Copilot Studio	Seleccione Clave de API, escriba el nombre del encabezado y el valor de la clave	Seleccione OAuth 2.0, escriba todas las URL de los puntos de conexión, el ID de cliente, el secreto y los ámbitos	Seleccione Autenticación básica, escriba el nombre de usuario y la contraseña
Enfoque de prueba	Pruebe con una solicitud GET usando la clave	Pruebe con una solicitud GET; el token debe ser válido y tener el ámbito correcto	Pruebe con una solicitud GET; las credenciales deben ser correctas

Ahora puede identificar y solucionar el error 401 No autorizado en su conector personalizado de Copilot Studio. Comience por verificar los requisitos de autenticación de la API y compárelos con la pestaña Autenticación del conector. Después de actualizar la configuración, pruebe siempre con una operación simple para confirmar la solución. Para los conectores de OAuth 2.0, considere habilitar los tokens de actualización para evitar la expiración del token durante conversaciones prolongadas.