Microsoft Copilot Studio Plugin Authentication: OAuth vs API Key Setup

When you build a plugin in Microsoft Copilot Studio, you must connect it to an external service such as a CRM, database, or custom API. The two most common authentication methods for these connections are OAuth 2.0 and API keys. Choosing the wrong method can cause connection failures, security gaps, or extra maintenance work. This article explains the technical differences between OAuth and API key authentication for Copilot Studio plugins. It also provides step-by-step setup instructions for both methods.

OAuth 2.0 and API Key Authentication Explained

Authentication determines how your Copilot Studio plugin proves its identity to the external service. OAuth 2.0 is an industry-standard protocol that uses tokens instead of direct credentials. The plugin requests an access token from an authorization server, then sends that token to the API. API key authentication is simpler: the plugin sends a static key value, usually in an HTTP header or query parameter, to authenticate each request.

OAuth 2.0 Technical Details

OAuth 2.0 supports multiple grant types. For Copilot Studio plugins, the authorization code grant is most relevant. This flow involves three parties: the plugin client, the authorization server, and the resource server. The plugin first obtains an authorization code after the user signs in. It then exchanges that code for an access token and optionally a refresh token. Access tokens expire after a set time, usually 60 minutes. The refresh token allows the plugin to get new tokens without user interaction. OAuth tokens are scoped, meaning the plugin can only access the specific resources defined in the scope parameter.

API Key Technical Details

An API key is a long string of characters assigned to a specific client. The key is static and does not expire unless manually revoked. The plugin sends the key with every request, typically in the Authorization header or as a custom header like X-API-Key. API keys do not support scopes or granular permissions. If a key is compromised, an attacker can use it until it is revoked. API keys are simpler to implement but offer less security than OAuth for user-facing operations.

Steps to Configure OAuth Authentication in Copilot Studio

Before you begin, register your plugin as an application in the external service’s developer portal. You need the client ID, client secret, authorization endpoint, and token endpoint. Copilot Studio supports standard OAuth 2.0 providers including Microsoft Entra ID, Google, and custom identity servers.

1. Open the plugin authentication settings
   In Copilot Studio, go to Plugins > select your plugin > Settings > Authentication. Click Edit next to the current authentication method.
2. Select OAuth 2.0 as the authentication type
   From the dropdown menu, choose OAuth 2.0. A form appears with fields for the authorization URL, token URL, client ID, client secret, and scopes.
3. Enter the authorization endpoint URL
   Paste the URL from your external service where the plugin redirects users for login. For Microsoft Entra ID, this is https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize. Replace {tenant-id} with your tenant ID.
4. Enter the token endpoint URL
   Paste the token exchange URL. For Entra ID, use https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token.
5. Provide client credentials
   Enter the client ID and client secret from the app registration. Keep the secret in a secure location. Copilot Studio encrypts the stored secret.
6. Define scopes
   Enter the required scopes as a space-separated list. For example, User.Read Mail.Read. Scopes limit the plugin to specific data.
7. Set the redirect URI
   Copy the redirect URI shown in Copilot Studio. Add this URI to your app registration in the external service. Without this step, OAuth fails with a redirect mismatch error.
8. Save and test
   Click Save. Then use the Test button in Copilot Studio to verify the connection. A successful test returns a 200 status code and sample data from the API.

Steps to Configure API Key Authentication in Copilot Studio

API key setup is faster than OAuth. You only need the key value and the header name expected by the external API. Most APIs document the exact header name in their developer guide.

1. Open the plugin authentication settings
   In Copilot Studio, navigate to Plugins > your plugin > Settings > Authentication. Click Edit.
2. Select API Key as the authentication type
   From the dropdown, choose API Key. The form now shows fields for Header Name and Key Value.
3. Enter the header name
   Type the exact header name the API expects. Common values are Authorization, X-API-Key, or Api-Key. Check the API documentation for the correct name.
4. Enter the key value
   Paste the API key string. This key is usually generated in the external service’s admin panel. The key may include hyphens, underscores, or alphanumeric characters.
5. Save and test the connection
   Click Save. Use the Test button to verify. A failed test means the header name or key value is incorrect. Review the API documentation for exact formatting.

Common Authentication Mistakes and How to Avoid Them

OAuth Redirect URI Mismatch Error

The most frequent OAuth error in Copilot Studio is a mismatch between the redirect URI in the app registration and the URI the plugin sends. Copy the redirect URI exactly from the plugin authentication page. Paste it into the external service’s app registration without any trailing slashes or spaces. If the error persists, check that the URI uses HTTPS.

API Key Exposed in Client-Side Code

If your plugin runs in a browser or mobile app, the API key is visible to anyone who inspects network traffic. Use OAuth instead of API keys for client-side plugins. If you must use an API key, restrict it to specific IP addresses or referrer domains in the external service settings.

OAuth Token Expiration Without Refresh

If your plugin fails after one hour, the access token expired and the plugin lacks a refresh token. Ensure the external service includes a refresh token in the token response and that Copilot Studio’s plugin settings have the refresh token endpoint configured. For Entra ID, add the offline_access scope to the scope list.

OAuth 2.0 vs API Key: Comparison for Copilot Studio Plugins

Item	OAuth 2.0	API Key
Security model	Token-based with scopes and expiration	Static key string
User context	Supports user-specific permissions	No user context; key is shared
Token rotation	Automatic via refresh tokens	Manual key rotation required
Setup complexity	Requires app registration, endpoints, scopes	One key and one header name
Best use case	User-facing plugins that access personal data	Server-to-server plugins or internal tools
Revocation	Revoke token or disable app registration	Delete or regenerate the key

Choose OAuth when your plugin needs to act on behalf of a specific user and requires granular permissions. Choose API key when the plugin runs in a trusted backend environment and the API does not support OAuth. Both methods work in Copilot Studio, but OAuth is the recommended approach for production plugins that handle sensitive data.

You can now configure OAuth or API key authentication for any Copilot Studio plugin using the steps above. For OAuth, always test the redirect URI and include the offline_access scope for token refresh. For API keys, restrict the key to specific IP ranges in the external service console. An advanced tip: use OAuth even for server-to-server plugins when possible because it provides automatic credential rotation through refresh tokens and reduces the risk of key compromise.