Integrate an API plugin with an API secured with a key

One of the common ways to secure APIs is by using API keys. API keys are arbitrary strings that API owners issue to grant you access to the API. Many popular services use API keys to secure access to their APIs. The API provider that issues API keys controls if a key gives you access to the whole API surface and all resources or only a specific part of it. The service also controls how long a key is valid.

API keys are convenient to use thanks to their simplicity. To call an API secured with an API key, all you need to do is to include the API key in the API request. The API then validates the key and either handles the request or rejects it with an authentication or authorization error. This simplicity comes however at a cost. API keys don't authenticate the user which means that the API can't act on the user's behalf. All users calling the API with the same API key, have the same permissions.

Each API provider defines how it expects you to pass the API key with your requests. For example, an API might require you to use a specific query string parameter or request header.

Microsoft 365 Copilot supports passing API keys as:

• JSON Web Token (JWT)

GET https://api.contoso.com/orders
Authorization: Bearer API_KEY 

• Query string parameter

GET https://api.contoso.com/orders?api_key=API_KEY

• Custom header

GET https://api.contoso.com/orders
X-API-Key: API_KEY

An API key is a secret value that you should never share publicly. When you build an API plugin that integrates with an API secured with an API key, you store the API key in a secure storage ___location in Microsoft 365, also known as vault. Then, in your app, you reference the ID of the vault entry. At runtime, declarative agent loads your plugin (2) and resolves the entry ID to the actual API key (3a) which it uses to call the API (3b). The following diagram illustrates this process.

Storing the API key in the vault allows you to securely manage your API key without ever exposing it publicly. Additionally, because your app doesn't reference the API key directly, you can update it without having to update your app.

During development, you can register your development API key in the vault yourself, either manually by going to the Teams Developer Portal and from the Tools section opening API key registration, or using Microsoft 365 Agents Toolkit. In production, typically an administrator registers the API key and gives you the ID of the vault entry to use in your API plugin.