Connect OpenAPI tools to Microsoft Foundry agents

Connect OpenAPI 3.0 and 3.1 tools to Microsoft Foundry agents using API key, managed identity, or anonymous authentication to integrate external APIs.

Connect your Microsoft Foundry agents to external APIs using OpenAPI 3.0 and 3.1 specifications. The Foundry model powering your agent can call external services, retrieve real-time data, and extend its capabilities beyond built-in functions.

OpenAPI specifications define a standard way to describe HTTP APIs so you can integrate existing services with your agents. Microsoft Foundry supports three authentication methods: anonymous, API key, and managed identity. For help choosing an authentication method, see Choose an authentication method.

Usage support

The following table shows SDK and setup support.

Microsoft Foundry support	Python SDK	C# SDK	JavaScript SDK	Java SDK	REST API	Basic agent setup	Standard agent setup
✔️	✔️	✔️	✔️	✔️	✔️	✔️	✔️

For Java, use the com.azure:azure-ai-agents package for OpenAPI agent tools. The com.azure:azure-ai-projects package doesn’t currently expose OpenAPI agent tool types.

Prerequisites

Before you begin, make sure you have:

• An Azure subscription with the right permissions.
• Azure RBAC role: Contributor or Owner on the Foundry project.
• A Foundry project created with an endpoint configured.
• An AI model deployed in your project.
• A basic or standard agent environment.
• SDK installed for your preferred language:
  • Python: azure-ai-projects
  • C#: Azure.AI.Extensions.OpenAI
  • TypeScript/JavaScript: @azure/ai-projects
  • Java: com.azure:azure-ai-agents

Environment variables

Variable	Description
FOUNDRY_PROJECT_ENDPOINT	Your Foundry project endpoint URL (not the external OpenAPI service endpoint).
FOUNDRY_MODEL_DEPLOYMENT_NAME	Your deployed model name.
OPENAPI_PROJECT_CONNECTION_NAME	(For API key auth) Your project connection name for the OpenAPI service.

• OpenAPI 3.0 or 3.1 specification file that meets these requirements:
  • Each function must have an operationId (required for the OpenAPI tool).
  • operationId should only contain letters, -, and _.
  • Use descriptive names to help models efficiently decide which function to use.
  • Supported request body content types: application/json, application/json-patch+json
• For managed identity authentication: Reader role or higher on target service resources.
• For API key/token authentication: a project connection configured with your API key or token. See Add a new connection to your project.

The FOUNDRY_PROJECT_ENDPOINT value refers to your Microsoft Foundry project endpoint, not the external OpenAPI service endpoint. You can find this endpoint in the Microsoft Foundry portal under your project’s Overview page. This endpoint is required to authenticate the agent service and is separate from any OpenAPI endpoints defined in your specification file.

Understand limitations

• Your OpenAPI spec must include operationId for each operation, and operationId can include only letters, -, and _.
• Supported request body content types: application/json, application/json-patch+json.
• For API key authentication, use one API key security scheme per OpenAPI tool. If you need multiple security schemes, create multiple OpenAPI tools.

Code example

• You need the latest SDK package. The .NET SDK is currently in preview. See the quickstart for details.
• If you use API key for authentication, your connection ID should be in the format of /subscriptions/{{subscriptionID}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.CognitiveServices/accounts/{{foundryAccountName}}/projects/{{foundryProjectName}}/connections/{{foundryConnectionName}}.

For API key authentication to work, your OpenAPI specification file must include:

1. A securitySchemes section with your API key configuration, such as the header name and parameter name.
2. A security section that references the security scheme.
3. A project connection configured with the matching key name and value.

Without these configurations, the API key isn’t included in requests. For detailed setup instructions, see the Authenticate with API key section.

You can also use token-based authentication (for example, a Bearer token) by storing the token in a project connection. For Bearer token auth, create a Custom keys connection with key set to Authorization and value set to Bearer <token> (replace <token> with your actual token). The word Bearer followed by a space must be included in the value. For details, see Set up a Bearer token connection.

Security and data considerations

When you connect an agent to an OpenAPI tool, the agent can send request parameters derived from user input to the target API.

• Use project connections for secrets (API keys and tokens). Avoid putting secrets in an OpenAPI spec file or source code.
• Review what data the API receives and what it returns before you use the tool in production.
• Use least-privilege access. For managed identity, assign only the roles the target service requires.

Authenticate with API key

By using API key authentication, you can authenticate your OpenAPI spec by using various methods such as an API key or Bearer token. You can use only one API key security schema per OpenAPI spec. If you need multiple security schemas, create multiple OpenAPI spec tools.

1. Update your OpenAPI spec security schemas. It has a securitySchemes section and one scheme of type apiKey. For example:

    "securitySchemes": {
        "apiKeyHeader": {
                "type": "apiKey",
                "name": "x-api-key",
                "in": "header"
            }
    }
   

   You usually only need to update the name field, which corresponds to the name of key in the connection. If the security schemes include multiple schemes, keep only one of them.

2. Update your OpenAPI spec to include a security section:

   "security": [
        {  
        "apiKeyHeader": []  
        }  
    ]
   

3. Remove any parameter in the OpenAPI spec that needs API key, because API key is stored and passed through a connection, as described later in this article.

4. Create a connection to store your API key.

5. Go to the Foundry portal and open your project.

6. Create or select a connection that stores the secret. See Add a new connection to your project.

If you regenerate the API key at a later date, you need to update the connection with the new key.

1. Enter the following information

   • key: name field of your security scheme. In this example, it should be x-api-key

            "securitySchemes": {
               "apiKeyHeader": {
                         "type": "apiKey",
                         "name": "x-api-key",
                         "in": "header"
                     }
             }
     

   • value: YOUR_API_KEY

2. After you create a connection, you can use it through the SDK or REST API. Use the tabs at the top of this article to see code examples.

Set up a Bearer token connection

You can use token-based authentication (for example, a Bearer token) with the same project_connection auth type used for API keys. The key difference is how you configure both the OpenAPI spec and the project connection.

Your OpenAPI spec will look like this:

  BearerAuth:
    type: http
    scheme: bearer
    bearerFormat: JWT

You need to:

1. Update your OpenAPI spec securitySchemes to use Authorization as the header name:

   "securitySchemes": {
       "bearerAuth": {
           "type": "apiKey",
           "name": "Authorization",
           "in": "header"
       }
   }
   

2. Add a security section that references the scheme:

   "security": [
       {
           "bearerAuth": []
       }
   ]
   

3. Create a Custom keys connection in your Foundry project:

   1. Go to the Foundry portal and open your project.
   2. Create or select a connection that stores the secret. See Add a new connection to your project.
   3. Enter the following values:
      • key: Authorization (must match the name field in your securitySchemes)
      • value: Bearer <token> (replace <token> with your actual token)

The value must include the word Bearer followed by a space before the token. For example: Bearer eyJhbGciOiJSUzI1NiIs.... If you omit Bearer , the API receives a raw token without the required authorization scheme prefix, and the request fails.

1. After you create the connection, use it with the project_connection auth type in your code, the same way you would for API key authentication. The connection ID uses the same format: /subscriptions/{{subscriptionID}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.CognitiveServices/accounts/{{foundryAccountName}}/projects/{{foundryProjectName}}/connections/{{foundryConnectionName}}.

Authenticate by using managed identity (Microsoft Entra ID)

Microsoft Entra ID is a cloud-based identity and access management service that your employees can use to access external resources. By using Microsoft Entra ID, you can add extra security to your APIs without needing to use API keys. When you set up managed identity authentication, the agent authenticates through the Foundry tool it uses.

Managed identity authentication only works when the target service accepts Microsoft Entra ID tokens. If the target API uses a custom authentication scheme that doesn’t support Microsoft Entra ID, use API key or Bearer token authentication instead.

Understand the audience URI

The audience (sometimes called resource identifier or Application ID URI) tells Microsoft Entra ID which service or API the token is intended to access. The audience value must match what the target service expects, or authentication fails with a 401 error.

The audience is not your Foundry project endpoint. It’s the resource identifier of the target service that your OpenAPI tool calls.

The following table lists audience URIs for common Azure services:

Target service	Audience URI
Azure Storage	https://storage.azure.com
Azure Key Vault	https://vault.azure.net
Azure AI Search	https://search.azure.com
Azure Logic Apps	https://logic.azure.com
Azure API Management (management plane)	https://management.azure.com
API protected by a Microsoft Entra app registration (including APIM with OAuth)	The Application ID URI from your app registration (for example, api://<client-id>)

If you use Azure API Management to protect a custom API with an OAuth 2.0 validation policy, the audience is the Application ID URI from the app registration that protects the API — not https://management.azure.com. The management plane audience only applies to Azure Resource Manager operations on the APIM resource itself.

For more information about how agents authenticate with Microsoft Entra ID, see Agent identity and authentication.

Find and verify your audience

Use the following steps to determine and verify the correct audience value:

• For Azure services: Check the service’s documentation for its Microsoft Entra ID resource identifier. Most Azure services list the audience URI in their authentication documentation.
• For APIs protected by a Microsoft Entra app registration: In the Azure portal, go to Microsoft Entra ID > App registrations > select your app > Expose an API. The Application ID URI at the top of the page is your audience value.
• To verify a token’s audience: Decode the access token at https://jwt.ms and check the aud claim. The aud value must match the audience your target service expects.

Set up managed identity authentication

To set up authentication by using Managed Identity:

1. Make sure your Foundry resource has system assigned managed identity enabled.

1. Create a resource for the service you want to connect to through OpenAPI spec.
2. Assign proper access to the resource.
   1. Select Access Control for your resource.
   2. Select Add and then add role assignment at the top of the screen.

1. Select the proper role assignment needed, usually it requires at least the READER role. Then select Next.
2. Select Managed identity and then select select members.
3. In the managed identity dropdown menu, search for Foundry Account and then select the Foundry account of your agent.
4. Select Finish.
5. When you finish the setup, you can continue by using the tool through the Foundry portal, SDK, or REST API. Use the tabs at the top of this article to see code samples.

Troubleshoot common errors

Symptom	Likely cause	Resolution
API key isn’t included in requests.	OpenAPI spec missing securitySchemes or security sections.	Verify your OpenAPI spec includes both components.securitySchemes and a top-level security section. Ensure the scheme name matches the key name in your project connection.
Agent doesn’t call the OpenAPI tool.	Tool choice not set or operationId not descriptive.	Use tool_choice="required" to force tool invocation. Ensure operationId values are descriptive so the model can choose the right operation.
Authentication fails for managed identity.	Managed identity not enabled or missing role assignment.	Enable system-assigned managed identity on your Foundry resource. Assign the required role (Reader or higher) on the target service.
Managed identity returns 401 even though the role is assigned.	Audience URI doesn’t match what the target service expects.	Verify the audience URI matches the target service’s resource identifier. For Azure services, check the service documentation. For Microsoft Entra-protected APIs, use the Application ID URI from your app registration. Decode the token at https://jwt.ms and confirm the aud claim matches. See Understand the audience URI.
Managed identity token rejected by target API.	Target service doesn’t accept Microsoft Entra ID tokens.	Confirm the target service supports Microsoft Entra ID authentication. If it doesn’t, use API key or Bearer token authentication instead.
Request fails with 400 Bad Request.	OpenAPI spec doesn’t match actual API.	Validate your OpenAPI spec against the actual API. Check parameter names, types, and required fields.
Request fails with 401 Unauthorized.	API key or token invalid or expired.	Regenerate the API key/token and update your project connection. Verify the connection ID is correct.
Tool returns unexpected response format.	Response schema not defined in OpenAPI spec.	Add response schemas to your OpenAPI spec for better model understanding.
operationId validation error.	Invalid characters in operationId.	Use only letters, -, and _ in operationId values. Remove numbers and special characters.
Connection not found error.	Connection name or ID mismatch.	Verify OPENAPI_PROJECT_CONNECTION_NAME matches the connection name in your Foundry project.
Bearer token not sent correctly.	Connection value missing Bearer prefix.	Set the connection value to Bearer <token> (with the word Bearer and a space before the token). Verify the OpenAPI spec securitySchemes uses "name": "Authorization".

Choose an authentication method

The following table helps you choose the right authentication method for your OpenAPI tool:

Authentication method	Best for	Setup complexity
Anonymous	Public APIs with no authentication	Low
API key	Non-Microsoft APIs with key-based access	Medium
Managed identity	Azure services and Microsoft Entra ID-protected APIs. Requires the target service to accept Microsoft Entra ID tokens and support Azure RBAC or Microsoft Entra-based access control.	Medium-High

Related content

• Add a new connection to your project
• Set up your environment for Foundry Agent Service
• Agent identity and authentication
• Expose an API and configure scopes (Microsoft Entra ID)
• Agents REST API (preview)