Understanding OpenAPI Targets Required Permissions Key considerations and limitations OpenAPI Specification and Feature Support Creating an OpenAPI target Updating an OpenAPI target Inline OpenAPI specifications

Adding an OpenAPI target

OpenAPI (formerly known as Swagger) is a widely used standard for describing RESTful APIs. Gateway supports OpenAPI 3.0 specifications for defining API targets.

Understanding OpenAPI Targets

OpenAPI targets connect your Gateway to REST APIs defined using OpenAPI specifications. The Gateway translates incoming MCP requests into HTTP requests to these APIs and handles the response formatting.

Key components of OpenAPI targets include:

OpenAPI Schema: The OpenAPI specification that describes the REST API
Credential Provider: Configuration for how the Gateway authenticates with the API
Outbound Auth: Configuration for authentication with external services

Required Permissions

For OpenAPI targets that use API Key or OAuth authentication, your Gateway's execution role needs permissions to access the credential provider:

For OAuth authentication:



{
  "Sid": "GetResourceOauth2Token",
  "Effect": "Allow",
  "Action": [
    "bedrock-agentcore:GetResourceOauth2Token"
  ],
  "Resource": [
    "arn:aws:agent-credential-provider:us-east-1:123456789012:token-vault/default/oauth2credentialprovider/abcdefghijk"
  ]
}

If the credentials are stored in AWS Secrets Manager, the execution role also needs permission to access those secrets:



{
  "Sid": "GetSecretValue",
  "Effect": "Allow",
  "Action": [
    "secretsmanager:GetSecretValue"
  ],
  "Resource": [
    "arn:aws:secretsmanager:us-east-1:123456789012:secret:your-secret-name"
  ]
}

Key considerations and limitations

Important

The OpenAPI specification must include operationId fields for all operations that you want to expose as tools. The operationId is used as the tool name in the MCP interface.

When using OpenAPI targets, keep in mind the following requirements and limitations:

OpenAPI versions 3.0 and 3.1 are supported (Swagger 2.0 is not supported)
The OpenAPI file must be free of semantic errors
The server attribute needs to have a valid URL of the actual endpoint
Only application/json content type is fully supported
Complex schema features like oneOf, anyOf, and allOf are not supported
Path parameter serializers and parameter serializers for query, header, and cookie parameters are not supported
Each LLM will have ToolSpec constraints. If OpenAPI has APIs/properties/object names not compliant to ToolSpec of the respective downstream LLMs, the data plane will fail. Common errors are property name exceeding the allowed length or the name containing unsupported character.

For best results with OpenAPI targets:

Always include operationId in all operations
Use simple parameter structures instead of complex serialization
Implement authentication and authorization outside of the specification
Stick to supported media types for maximum compatibility

OpenAPI Specification and Feature Support

The OpenAPI specification defines the REST API that your Gateway will expose. Here's an example of a simple OpenAPI specification:

OpenAPI Feature Support

The following table outlines the OpenAPI features that are supported and unsupported by Gateway:

OpenAPI Feature Support
Supported Features	Unsupported Features
Schema Definitions Basic data types (string, number, integer, boolean, array, object) Required field validation Nested object structures Array definitions with item specifications	Schema Composition oneOf specifications anyOf specifications allOf specifications
HTTP Methods Standard HTTP methods (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)	Security Schemes Security schemes at the OpenAPI specification level (authentication must be configured using the Gateway's outbound authorization configuration)
Media Types application/json application/xml multipart/form-data application/x-www-form-urlencoded	Media Types Custom media types beyond the supported list Binary media types
Path Parameters Simple path parameter definitions (Example: /users/{userId})	Parameter Serialization Complex path parameter serializers (Example: `/users{;id\*}{?metadata}`) Query parameter arrays with complex serialization Header parameter serializers Cookie parameter serializers
Query Parameters Basic query parameter definitions Simple string, number, and boolean types	Callbacks and Webhooks Callback operations Webhook definitions
Request/Response Bodies JSON request and response bodies XML request and response bodies Standard HTTP status codes (200, 201, 400, 404, 500, etc.)	Links Links between operations

OpenAPI Specification Format

When using OpenAPI specifications with Gateway, ensure that your API definitions adhere to the supported features and avoid using unsupported features to prevent errors during target creation and invocation.

Following shows an example of a supported OpenAPI specification

Example of a supported OpenAPI specification:



{
  "openapi": "3.0.0",
  "info": {
    "title": "Weather API",
    "version": "1.0.0",
    "description": "API for retrieving weather information"
  },
  "paths": {
    "/weather": {
      "get": {
        "summary": "Get current weather",
        "description": "Returns current weather information for a location",
        "operationId": "getCurrentWeather",
        "parameters": [
          {
            "name": "location",
            "in": "query",
            "description": "City name or coordinates",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "units",
            "in": "query",
            "description": "Units of measurement (metric or imperial)",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["metric", "imperial"],
              "default": "metric"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "location": {
                      "type": "string"
                    },
                    "temperature": {
                      "type": "number"
                    },
                    "conditions": {
                      "type": "string"
                    },
                    "humidity": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "404": {
            "description": "Location not found"
          }
        }
      }
    }
  }
}

Following shows another example of a supported OpenAPI specification.



{
  "openapi": "3.0.0",
  "info": {
    "title": "Search API",
    "version": "1.0.0",
    "description": "API for searching content"
  },
  "servers": [
    {
      "url": "https://api.example.com/v1"
    }
  ],
  "paths": {
    "/search": {
      "get": {
        "summary": "Search for content",
        "operationId": "searchContent",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "description": "Search query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "title": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string"
                          },
                          "snippet": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request"
          }
        }
      }
    }
  }
}

The following shows an example of an unsupported schema with oneOf:



{
  "oneOf": [
    {"$ref": "#/components/schemas/Pencil"},
    {"$ref": "#/components/schemas/Pen"}
  ]
}

Creating an OpenAPI target

You can add an OpenAPI target to your Gateway using one of the following methods:

Console

To add an OpenAPI target to an existing gateway

Open the AgentCore console at https://console.aws.amazon.com/bedrock-agentcore/home#.
Choose Gateways.
Select the gateway to which you want to add a target.
Choose the Targets tab.
Choose Add target.
Enter a Target name.
(Optional) Provide an optional Target description.
For Target type, choose REST API to connect to a REST API Service.
Choose OpenAPI schema
For OpenAPI schema, choose to either provide the schema inline or reference an Amazon S3 location containing your OpenAPI specification.
(Optional) In the Outbound authentication section, configure authentication for accessing external services:
- For Authentication type, choose OAuth client or API key.
- Select the appropriate authentication resource from your account.
Choose Add target.

AgentCore SDK

You can add an OpenAPI target with API Key authentication using the AgentCore SDK:



from bedrockagentcoresdk.gateway import GatewayClient
  
# Initialize the Gateway client
gateway_client = GatewayClient(region_name="us-west-2")
  
# Create an OpenAPI target with API Key authentication
open_api_target = gateway_client.create_mcp_gateway_target(
    gateway=gateway,
    target_type="openApiSchema",
    target_payload={
        "s3": {
            "uri": "s3://your-bucket/path/to/open-api-spec.json"
        }
    },
    credentials={
        "api_key": "your-api-key",
        "credential_location": "HEADER",
        "credential_parameter_name": "X-API-Key"
    }
)

You can also add an OpenAPI target with OAuth authentication:



# Create an OpenAPI target with OAuth authentication
open_api_with_oauth_target = gateway_client.create_mcp_gateway_target(
    gateway=gateway, 
    target_type="openApiSchema",
    target_payload={
        "s3": {
            "uri": "s3://your-bucket/path/to/open-api-spec.json"
        }
    },
    credentials={"oauth2_provider_config": {"customOauth2ProviderConfig": {
      "oauthDiscovery": {
        "authorizationServerMetadata": {
          "issuer": "https://example.auth0.com",
          "authorizationEndpoint": "https://example.auth0.com/authorize",
          "tokenEndpoint": "https://example.auth0.com/oauth/token"
        }
      },
      "clientId": "your-client-id",
      "clientSecret": "your-client-secret"
    }}}
)

Boto3

The following Python code shows how to add an OpenAPI target using boto3 (AWS SDK for Python):



import boto3
  
# Create the agentcore client
agentcore_client = boto3.client('bedrock-agentcore-control')
  
# Create an OpenAPI target with API Key authentication
target = agentcore_client.create_gateway_target(
    gatewayIdentifier="your-gateway-id",
    name="SearchAPITarget",
    targetConfiguration={
        "mcp": {
            "openApiSchema": {
                "s3": {
                    "uri": "s3://your-bucket/path/to/open-api-spec.json",
                    "bucketOwnerAccountId": "123456789012"
                }
            }
        }
    },
    credentialProviderConfigurations=[
        {
            "credentialProviderType": "API_KEY",
            "credentialProvider": {
                "apiKeyCredentialProvider": {
                    "providerArn": "arn:aws:agent-credential-provider:us-east-1:123456789012:token-vault/default/apikeycredentialprovider/abcdefghijk",
                    "credentialLocation": "HEADER",
                    "credentialParameterName": "X-API-Key"
                }
            }
        }
    ]
)

API

Use the CreateGatewayTarget operation to add an OpenAPI target to your Gateway:



PUT /gateways/abc123def4/targets/ HTTP/1.1
Content-Type: application/json

{
  "name": "SearchAPITarget",
  "description": "Target for search API",
  "targetConfiguration": {
    "mcp": {
      "openApiSchema": {
        "s3": {
          "uri": "s3://your-bucket/path/to/open-api-spec.json"
        }
      }
    }
  },
  "credentialProviderConfigurations": [
    {
      "credentialProviderType": "API_KEY",
      "credentialProvider": {
        "apiKeyCredentialProvider": {
          "providerArn": "arn:aws:agent-credential-provider:us-east-1:123456789012:token-vault/default/apikeycredentialprovider/abcdefghijk",
          "credentialLocation": "HEADER",
          "credentialParameterName": "X-API-Key"
        }
      }
    }
  ]
}

Updating an OpenAPI target

You can update an existing OpenAPI target using the UpdateGatewayTarget API:



updated_target = agentcore_client.update_gateway_target(
    gatewayIdentifier="your-gateway-id",
    targetId="your-target-id",
    name="UpdatedSearchAPITarget",
    targetConfiguration={
        "mcp": {
            "openApiSchema": {
                "s3": {
                    "uri": "s3://your-bucket/path/to/updated-open-api-spec.json"
                }
            }
        }
    },
    credentialProviderConfigurations=[
        {
            "credentialProviderType": "API_KEY",
            "credentialProvider": {
                "apiKeyCredentialProvider": {
                    "providerArn": "arn:aws:agent-credential-provider:us-east-1:123456789012:token-vault/default/apikeycredentialprovider/abcdefghijk",
                    "credentialLocation": "HEADER",
                    "credentialParameterName": "X-API-Key"
                }
            }
        }
    ]
)

Inline OpenAPI specifications

For small OpenAPI specifications, you can provide the specification inline when creating the target:



target = gateway_client.create_mcp_gateway_target(
    gateway=gateway,
    target_type="openApiSchema",
    target_payload={
        "inlinePayload": """
        {
          "openapi": "3.0.0",
          "info": {
            "title": "Simple API",
            "version": "1.0.0"
          },
          "paths": {
            "/hello": {
              "get": {
                "operationId": "sayHello",
                "parameters": [
                  {
                    "name": "name",
                    "in": "query",
                    "schema": {
                      "type": "string"
                    }
                  }
                ],
                "responses": {
                  "200": {
                    "description": "OK",
                    "content": {
                      "application/json": {
                        "schema": {
                          "type": "object",
                          "properties": {
                            "message": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
        """
    }
)

Example OpenAPI target configuration with inline schema:


{
  "name": "OpenAPITarget",
  "targetConfiguration": {
    "mcp": {
      "openApiSchema": {
        "inlinePayload": "{\"openapi\":\"3.0.0\",\"info\":{\"title\":\"Listing Application API\",\"description\":\"A simple API for creating, reading, updating, and deleting listings\",\"version\":\"1.0.0\"},\"paths\":{\"/listings\":{\"get\":{\"operationId\":\"listListings\",\"responses\":{\"200\":{\"description\":\"Successful operation\"}}}}}}"
      }
    }
  },
  "credentialProviderConfigurations": [{
    "credentialProviderType": "GATEWAY_IAM_ROLE"
  }]
}


{
  "name": "OpenAPITarget",
  "targetConfiguration": {
    "mcp": {
      "openApiSchema": {
        "s3": {
          "uri": "s3://my-bucket/api-specs/openapi.json",
          "bucketOwnerAccountId": "123456789012"
        }
      }
    }
  },
  "credentialProviderConfigurations": [{
    "credentialProviderType": "GATEWAY_IAM_ROLE"
  }]
}

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Adding Lambda targets

Adding Smithy targets