Copilot Studio Custom Connector Returns 401 Unauthorized: Fix

When building a custom connector in Copilot Studio, you may see a 401 Unauthorized error when the connector tries to call an external API. This error means the API rejected the request because no valid authentication credentials were provided. The root cause is almost always a mismatch between the authentication method configured in the connector and what the API expects. This article explains why the 401 error occurs and provides step-by-step fixes for the most common authentication scenarios.

Why the 401 Unauthorized Error Occurs

The 401 Unauthorized error is an HTTP status code that means the API server received your request but will not process it because the authentication is missing, invalid, or expired. In Copilot Studio custom connectors, this happens when the authentication configuration does not match what the external API expects.

There are three common root causes:

Wrong Authentication Type

Each API supports a specific authentication method. If you select API Key in the connector but the API expects OAuth 2.0, the server will reject the request with a 401 error. The connector must use the exact method defined in the API’s documentation.

Incorrect Credentials or Token

Even with the correct authentication type, the actual credentials must be valid. An API key may have expired, an OAuth token may have been revoked, or a username and password combination may be wrong. Copilot Studio does not validate credentials until the connector is tested or used in a conversation.

Missing or Misnamed Parameters

For API Key authentication, the connector must send the key in the correct header or query parameter. For example, if the API expects the key in a header called X-API-Key but the connector sends it in Authorization, the API returns 401. The same applies to OAuth scopes, grant types, and token endpoints.

Steps to Fix the 401 Unauthorized Error

Follow these steps in order. Each step addresses one of the root causes above.

Step 1: Verify the API’s Authentication Requirements

1. Open the API documentation
   Locate the official documentation for the API you are connecting to. Look for the Authentication section. Note the exact authentication type — API Key, OAuth 2.0, Basic Auth, or another method.
2. Record the exact parameter names
   For API Key, note the header name or query parameter name. For OAuth 2.0, note the authorization URL, token URL, client ID, client secret, scopes, and grant type. For Basic Auth, note that the API expects a Base64-encoded username:password string sent in the Authorization header.

Step 2: Check the Connector’s Authentication Configuration

1. Sign in to Copilot Studio
   Go to https://copilotstudio.microsoft.com and open your copilot.
2. Navigate to Custom connectors
   Select Settings in the top-right corner, then choose Custom connectors. Find the connector returning the 401 error and click Edit.
3. Review the Authentication tab
   Click the Authentication tab. Compare the selected authentication type with the API documentation. If they do not match, change the authentication type to the correct one.
4. Update the parameters
   For API Key, enter the exact header name or query parameter name from the documentation. For OAuth 2.0, enter the authorization URL, token URL, client ID, client secret, and scopes exactly as specified. For Basic Auth, enter the username and password.

Step 3: Test the Connector with a Simple Operation

1. Create a test operation
   In the connector editor, go to the Definition tab and add a new operation that makes a simple GET request to a public endpoint of the API that requires minimal data.
2. Click Test operation
   Select the test operation and click Test operation in the toolbar. A dialog appears showing the request and response. If the response is 200 OK, the authentication is configured correctly. If you still see 401, proceed to the next step.

Step 4: Validate Credentials Outside of Copilot Studio

1. Use a tool like Postman or curl
   Send the same request to the API using the same authentication method and credentials. If you get a 200 response, the credentials are valid and the issue is in the connector configuration. If you get 401, the credentials themselves are wrong or expired.
2. Renew or replace credentials
   If the credentials are invalid, generate a new API key, refresh the OAuth token, or reset the password. Then update the connector with the new credentials.

Step 5: Check for Policy or Scope Restrictions

1. Review API access policies
   Some APIs restrict access based on IP address, user agent, or request frequency. Ensure the Copilot Studio connector’s requests are not blocked by such policies.
2. Verify OAuth scopes
   For OAuth 2.0, the token must include the scopes required by the API endpoint. Add the missing scopes in the connector’s Authentication tab and regenerate the token.

If the 401 Error Persists After the Main Fix

Sometimes the error continues even after you verify the authentication type and credentials. The following issues are less common but equally important to check.

Custom Connector Uses a Shared Connection Reference

If your connector uses a connection reference that is shared across multiple environments, the credentials stored in that reference may be outdated. Go to the Power Platform admin center, find the connection reference, and update the credentials. Then retest the connector in Copilot Studio.

API Gateway or Proxy Adds Authentication

Some APIs sit behind a gateway that requires its own authentication, such as Azure API Management. In that case, the custom connector must include both the gateway authentication and the backend API authentication. Configure the connector to send the gateway credentials in the request header and the backend credentials in the body or a separate header.

OAuth Token Expires During a Conversation

If the connector works during testing but returns 401 after a few minutes in a live copilot, the OAuth token may have expired. Configure the connector to use a refresh token if the API supports it. In the Authentication tab, enable the refresh token option and provide the refresh token URL and any required parameters.

Copilot Studio Custom Connector Authentication Methods: Comparison

Item	API Key	OAuth 2.0	Basic Auth
Description	A static key sent in a header or query parameter	Token-based delegation using authorization and token endpoints	Username and password sent as a Base64-encoded string
Common use case	Simple public APIs, weather services, payment gateways	Microsoft Graph, Salesforce, Google APIs, social media APIs	Legacy APIs, internal corporate APIs with basic security
Credential expiry	Often static, but may be rotated	Token expires in minutes to hours; refresh token may extend	Static until password is changed
Configuration in Copilot Studio	Select API Key, enter header name and key value	Select OAuth 2.0, enter all endpoint URLs, client ID, secret, scopes	Select Basic Auth, enter username and password
Testing approach	Test with a GET request using the key	Test with a GET request; token must be valid and scoped	Test with a GET request; credentials must be correct

Now you can identify and fix the 401 Unauthorized error in your Copilot Studio custom connector. Start by verifying the API’s authentication requirements and comparing them with the connector’s Authentication tab. After updating the configuration, always test with a simple operation to confirm the fix. For OAuth 2.0 connectors, consider enabling refresh tokens to avoid token expiry during extended conversations.