Official documentation checked October 14, 2026.
To authenticate an API-backed tool in Copilot Studio, first identify the integration you are building. This guide covers a Power Platform custom connector used as an agent tool. Its authentication configuration is not the same as the agent’s own sign-in settings, a SharePoint knowledge source, or every other integration previously called a plugin.
OAuth and API keys are not interchangeable switches that any API accepts. Choose a method supported by the service, then decide whether requests must be authorized for each user or for a deliberately shared service identity.
1. Decide whose permissions the tool must use
For personal documents, employee records, or actions taken on someone’s behalf, preserve that user’s access boundary. Signing into the agent alone does not prove that the API call uses the same person’s permissions. Conversely, an API key typically identifies the key’s owner or application, not automatically the person chatting.
Write down the intended operation, data audience, account owner, required permissions, and credential-rotation owner before implementation. For example, a shared weather lookup and a tool that changes an employee’s leave balance have very different authorization requirements.
API-key permissions and expiration depend on the provider; keys are not inherently unlimited or permanent. OAuth can support delegated access and renewal, but does not make every permission request safe or rotate a client secret automatically. The supported custom-connector authentication methods and OAuth limitations are listed in Microsoft’s connection-parameter reference. In particular, this connector mechanism does not support the OAuth client-credentials grant.
2. Configure OAuth in the custom connector
Open the custom connector in Power Apps or Power Automate and use its Security section. For OAuth, select the supported identity provider and supply the application details and endpoints required by that provider. Have the API owner confirm the resource and minimum scopes for the operations you will expose; Microsoft Graph mail permissions are not a generic requirement for an unrelated API.
Register the redirect URI shown for this connector exactly as required by the identity provider. Do not replace it with a guessed common URL or strip a trailing slash indiscriminately. A mismatch can break sign-in even when the client ID and credential are valid.
Keep any client secret in the designated protected configuration field and your approved credential-management system. Do not put it into the OpenAPI example payload, agent instructions, browser code, or a chat message. If the selected provider supports renewal, configure it according to that provider’s requirements; do not add a scope such as offline_access blindly to every API.
Microsoft’s custom-connector creation and troubleshooting guide identifies the Security tab and per-connector redirect URI. Test sign-in before adding the tool to a production agent.
3. Configure an API-key connection without exposing the key
In the connector’s Security section, select API Key only if the target API supports it. Define the requested label, parameter name, and location to match the service’s specification. A header name such as X-API-Key is merely an example; copying it into an API that expects a different header will fail.
The definition describes where the credential goes. The actual secret is supplied when creating the connection, including through Test > New connection in the connector designer. Do not hard-code a live key into the operation definition or a default input. Prefer a header when the provider supports it; query-string credentials can appear in logged URLs.
Use a dedicated, minimally privileged key where the provider offers one, with an owner and rotation procedure. Client-side referrer restrictions or IP filtering do not make a secret safe to publish in a downloadable web page. If only a broad account-wide key is available, assess the agent’s audience and exposed actions before sharing the tool.
4. Add the connector operation and check runtime identity
In Copilot Studio, open the agent’s Tools page, select Add a tool, choose the connector and operation, and select or establish its connection. A new custom connector can also be started from Add a tool > New tool > Custom connector, which opens the connector-authoring experience. See Microsoft’s connector-tool instructions.
Check the tool’s credential choice separately from the OAuth/API-key mechanism. A maker-provided connection can let users exercise the maker’s access, even when those users could not reach the data themselves. Do not use it as a shortcut around consent or permission failures. Microsoft’s maker-credential guidance explains this oversharing risk and the administrator controls.
Expose only the operations needed for the agent’s job. Test a read operation before allowing writes or deletions, and require appropriate user review for consequential actions.
5. Test authorization, error handling, and credential replacement
Use non-sensitive test records and verify more than a successful HTTP response. Check that the requested record and operation are correct, an authorized user can complete the task, and an unauthorized user cannot. Expected success codes vary by API; not every valid operation returns 200 or a response body.
Test in the actual published channel as well as the designer. User-authenticated tools have channel requirements; a demo website is not equivalent to every supported deployment. Follow the current user-authentication and channel guidance.
For a failed request, record the operation, timestamp, status, and redacted provider error. Never attach the Authorization header, token, or key. For planned credential replacement, identify all dependent connections, update a test connection first, verify the intended permissions, then coordinate production rotation with the owner. Revoke an exposed credential through the provider’s incident process; do not merely remove it from a visible screenshot.
Keep the connector definition, required scopes, connection owner, tested channel, and last verification date in the maintenance record. That makes future authentication failures diagnosable without broadening access.