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.

Consider adding this tool using a toolbox. By using a toolbox, you are able to reuse the tool across agents and runtimes, as well as centralizing credential management, versioning, and policy enforcement through a managed MCP endpoint. See the toolbox quickstart.

Prerequisites

Before you begin, make sure you have:

• An Azure subscription with the right permissions.
• Foundry User role on the Foundry project to create and run agents.

The Foundry RBAC roles were recently renamed. Foundry User, Foundry Owner, Foundry Account Owner, and Foundry Project Manager were previously named Azure AI User, Azure AI Owner, Azure AI Account Owner, and Azure AI Project Manager. You might still see the previous names in some places while the rename rolls out. The role IDs and core permissions are unchanged by the rename.

• Foundry Project Manager role on the Foundry project if you create a project connection for API key or token authentication.
• A Foundry project created with an endpoint configured.
• An AI model deployed in your project. Confirm that both the model and project region support OpenAPI tools in Tool support by region and model.
• A basic or standard agent environment.
• SDK installed for your preferred language:
  • Python: pip install azure-ai-projects jsonref
  • 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: the least-privileged target-service role that permits the required API operations, assigned to the Foundry project’s managed identity at the target resource scope.
• 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.

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.

Run the anonymous first-success flow

Start with the anonymous weather API to verify that your agent can load an OpenAPI specification and call an operation. This path doesn’t require an external API credential or a Foundry project connection.

1. Install the SDK package for your selected language from Prerequisites.
2. Download weather_openapi.json, and save it to the assets path used by the sample.
3. Set your Foundry project endpoint and model deployment values.
4. Run the anonymous sample in your selected language section.
5. Confirm that the response contains current weather for Seattle, and then delete the agent version created by the sample.

After the anonymous call succeeds, configure the authentication required by your target API. Keep API key authentication, bearer-token authentication, and managed identity authentication as separate variants.

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.
• Rotate API keys and bearer tokens regularly and immediately after suspected exposure. Update the project connection when credentials change; don’t place credentials in the OpenAPI specification or source code.

Add OpenAPI tools to a toolbox

Use this pattern to expose any REST API described by an OpenAPI spec. Choose the auth.type that matches your API’s security model.

When you use managed identity auth, assign only the least-privileged RBAC role that permits the required API operations to your Foundry project’s managed identity on the target service. For example, assign Reader on the target Azure resource only when the API needs read-only Azure Resource Manager access. Without the required assignment, the agent receives a 401 Unauthorized response when calling the API. For full setup steps, see Authenticate by using managed identity.

Create an OpenAPI toolbox with the Azure Developer CLI

OpenAPI tools embed the spec directly under tools:. Connection-based auth (connection_auth) references a project connection; anonymous OpenAPI tools need no connection.

Step 1. (Optional) Create the auth connection

Skip this step for anonymous OpenAPI tools.

# API-key auth (passed by the platform on every call)
# Set OPENAPI_AUTHORIZATION_HEADER in your shell without committing its value.
azd ai connection create my-api-conn \
  --kind remote-tool \
  --target https://api.example.com \
  --auth-type custom-keys \
  --custom-key "Authorization=$OPENAPI_AUTHORIZATION_HEADER"

OpenAPI tools also accept --auth-type oauth2 connections. For the full set of azd ai connection create flags, see Toolbox MCP authentication and configuration.

Step 2. Define the toolbox

The OpenAPI spec is inline under tools[].openapi.spec.

# my-toolbox.yaml
description: OpenAPI toolbox
tools:
  - type: openapi
    name: my-api
    openapi:
      name: my-api
      spec:
        openapi: "3.0.1"
        info:
          title: "My API"
          version: "1.0"
        servers:
          - url: https://api.example.com/v1
        paths:
          /search:
            get:
              operationId: search
              parameters:
                - name: query
                  in: query
                  required: true
                  schema:
                    type: string
              responses:
                "200":
                  description: OK
      auth:
        type: connection_auth
        connection_id: my-api-conn

For anonymous APIs, replace the auth: block with:

      auth:
        type: anonymous
        security_scheme:
          type: anonymous

Step 3. Create the toolbox

azd ai toolbox create my-toolbox --from-file my-toolbox.yaml

Before you run the code samples

• Download the maintained tripadvisor_openapi.json specification and save it to the assets path used by your language sample.

• 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

Use this variant for an API that expects a key in a header or query parameter. You can use only one API key security scheme per OpenAPI tool. If the API requires multiple security schemes, create multiple OpenAPI 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

Use this variant for an API that expects a bearer token in the Authorization header. It uses the same project_connection auth type as API-key authentication, but the OpenAPI security scheme and connection values differ.

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 the Bearer prefix and following space, 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 least-privileged data-plane or application role that grants the operations in your OpenAPI specification. Azure Resource Manager Reader access alone doesn’t grant data-plane access. 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 target service’s least-privileged data-plane or application role for the operations in your OpenAPI specification.
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 is missing the Bearer prefix and following space.	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)
• Microsoft Foundry REST API reference