Düzenle

Configure API key authentication

Some APIs use API keys for authorization. An API key is a shared secret that the client includes in API requests to authenticate and gain access. API plugins support sending the API key in three ways:

  • As a bearer token in the Authorization header
  • As a value in a custom header
  • As a query parameter

Note

API key authentication applies to API plugins (built from an OpenAPI document) only. Model Context Protocol (MCP) plugins don't support API key authentication. For MCP plugins, use OAuth 2.0 (including dynamic client registration) or Microsoft Entra SSO authentication.

Configure API key authentication in two steps: add the API key to your OpenAPI document and create the API key auth config.

Step 1: Add the API key to your OpenAPI document

Microsoft 365 Copilot determines how to send the API key based on the securitySchemes entry in your OpenAPI document.

Bearer token

If your API accepts the API key as a bearer token, enable Bearer authentication in your OpenAPI document. For more information, see Bearer authentication.

securitySchemes:
  BearerAuth:
    type: http
    scheme: bearer

Custom header

If your API accepts the API key in a custom header, enable API key authentication in your OpenAPI document with the in property set to header and the name property set to the header name. For more information, see API Keys.

securitySchemes:
  ApiKeyAuth:
    type: apiKey
    in: header
    name: X-API-KEY

Query parameter

If your API accepts the API key in a query parameter, enable API key authentication in your OpenAPI document by setting the in property to query and the name property to the name of the query parameter. For more information, see API Keys.

securitySchemes:
  ApiKeyAuth:
    type: apiKey
    in: query
    name: api_key

Step 2: Create the API key auth config

API key authentication relies on an authentication configuration (auth config) - a record stored in the Microsoft Enterprise token store that Microsoft 365 Copilot uses to send the API key when your plugin calls the API. You can create the auth config by using Microsoft 365 Agents Toolkit or the Microsoft Teams developer portal. The declarative agent developer skill doesn't support API key authentication, because it builds MCP plugins.

When you create an API plugin from an existing OpenAPI document in Microsoft 365 Agents Toolkit, the toolkit registers the API key, creates the auth config, and updates your plugin manifest for you. You must define the securitySchemes property in your OpenAPI document.

Use the Teams developer portal

Registering in the Teams developer portal is optional if you use Agents Toolkit. Use it to create the auth config manually, or to manage an auth config that Agents Toolkit already created.

  1. Open Teams developer portal. Select Tools -> API key registration.

  2. If you have no existing registrations, select Create an API key. If you have existing registrations, select New API key.

  3. Select Add secret and enter the API key.

  4. Fill in the following fields.

    • API key name: A friendly name for your registration.
    • Base URL: Your API's base URL. This value should correspond to an entry in the servers array in your OpenAPI document.
    • Target tenant: Limit API access to your home tenant, or allow any tenant.
    • Target Teams App: Select Any Teams app if you don't know your final app ID. After you publish your app, bind this registration with your published app ID.

  5. Select Save.

  6. Completing the registration generates an auth config ID (currently labeled API key registration ID in the Teams developer portal).

Add the auth config ID to the plugin manifest

When you create the auth config manually in the Teams developer portal, set the type property of the runtime authentication object to ApiKeyPluginVault, and set the reference_id to the auth config ID. Agents Toolkit does this for you.

"auth": {
  "type": "ApiKeyPluginVault",
  "reference_id": "auth config ID"
},

Related content

  • Last updated on