CreateGateway
Creates a gateway for Amazon Bedrock Agent. A gateway serves as an integration point between your agent and external services.
If you specify CUSTOM_JWT as the authorizerType, you must provide an authorizerConfiguration.
Request Syntax
POST /gateways/ HTTP/1.1
Content-type: application/json
{
"authorizerConfiguration": { ... },
"authorizerType": "string",
"clientToken": "string",
"description": "string",
"domainOverride": {
"alternateDomains": [ "string" ],
"default": "string"
},
"exceptionLevel": "string",
"interceptorConfigurations": [
{
"inputConfiguration": {
"passRequestHeaders": boolean,
"payloadFilter": {
"exclude": [
{ ... }
]
}
},
"interceptionPoints": [ "string" ],
"interceptor": { ... }
}
],
"kmsKeyArn": "string",
"name": "string",
"policyEngineConfiguration": {
"arn": "string",
"mode": "string"
},
"protocolConfiguration": { ... },
"protocolType": "string",
"roleArn": "string",
"tags": {
"string" : "string"
}
}
URI Request Parameters
The request does not use any URI parameters.
Request Body
The request accepts the following data in JSON format.
-
The authorizer configuration for the gateway. Required if
authorizerTypeisCUSTOM_JWT.Type: AuthorizerConfiguration object
Note: This object is a Union. Only one member of this object can be specified or returned.
Required: No
-
The type of authorizer to use for the gateway.
-
CUSTOM_JWT- Authorize with a bearer token. -
AWS_IAM- Authorize with your AWS IAM credentials. -
NONE- No authorization
Type: String
Valid Values:
CUSTOM_JWT | AWS_IAM | NONE | AUTHENTICATE_ONLYRequired: Yes
-
- clientToken
-
A unique, case-sensitive identifier to ensure that the API request completes no more than one time. If you don't specify this field, a value is randomly generated for you. If this token matches a previous request, the service ignores the request, but doesn't return an error. For more information, see Ensuring idempotency.
Type: String
Length Constraints: Minimum length of 33. Maximum length of 256.
Pattern:
[a-zA-Z0-9](-*[a-zA-Z0-9]){0,256}Required: No
- description
-
The description of the gateway.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 200.
Required: No
- domainOverride
-
The public domain names that the gateway advertises in its OAuth discovery URLs instead of the inbound Host header. Specify this when clients reach the gateway through your own proxy or custom domain.
Type: DomainOverride object
Required: No
- exceptionLevel
-
The level of detail in error messages returned when invoking the gateway.
-
If the value is
DEBUG, granular exception messages are returned to help a user debug the gateway. -
If the value is omitted, a generic error message is returned to the end user.
Type: String
Valid Values:
DEBUGRequired: No
-
- interceptorConfigurations
-
A list of configuration settings for a gateway interceptor. Gateway interceptors allow custom code to be invoked during gateway invocations.
Type: Array of GatewayInterceptorConfiguration objects
Array Members: Minimum number of 1 item. Maximum number of 2 items.
Required: No
- kmsKeyArn
-
The Amazon Resource Name (ARN) of the AWS KMS key used to encrypt data associated with the gateway.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 2048.
Pattern:
arn:aws(|-cn|-us-gov):kms:[a-zA-Z0-9-]*:[0-9]{12}:key/[a-zA-Z0-9-]{36}Required: No
- name
-
The name of the gateway. The name must be unique within your account.
Type: String
Pattern:
([0-9a-zA-Z][-]?){1,48}Required: Yes
- policyEngineConfiguration
-
The policy engine configuration for the gateway. A policy engine is a collection of policies that evaluates and authorizes agent tool calls. When associated with a gateway, the policy engine intercepts all agent requests and determines whether to allow or deny each action based on the defined policies.
Type: GatewayPolicyEngineConfiguration object
Required: No
- protocolConfiguration
-
The configuration settings for the protocol specified in the
protocolTypeparameter.Type: GatewayProtocolConfiguration object
Note: This object is a Union. Only one member of this object can be specified or returned.
Required: No
- protocolType
-
The protocol type for the gateway.
Type: String
Valid Values:
MCPRequired: No
- roleArn
-
The Amazon Resource Name (ARN) of the IAM role that provides permissions for the gateway to access AWS services.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 2048.
Pattern:
arn:aws(-[^:]+)?:iam::([0-9]{12})?:role/.+Required: Yes
-
A map of key-value pairs to associate with the gateway as metadata tags.
Type: String to string map
Map Entries: Minimum number of 0 items. Maximum number of 50 items.
Key Length Constraints: Minimum length of 1. Maximum length of 128.
Key Pattern:
[a-zA-Z0-9\s._:/=+@-]*Value Length Constraints: Minimum length of 0. Maximum length of 256.
Value Pattern:
[a-zA-Z0-9\s._:/=+@-]*Required: No
Response Syntax
HTTP/1.1 202
Content-type: application/json
{
"authorizerConfiguration": { ... },
"authorizerType": "string",
"createdAt": "string",
"customTransformConfiguration": {
"lambda": {
"arn": "string"
}
},
"description": "string",
"domainOverride": {
"alternateDomains": [ "string" ],
"default": "string"
},
"exceptionLevel": "string",
"gatewayArn": "string",
"gatewayId": "string",
"gatewayUrl": "string",
"interceptorConfigurations": [
{
"inputConfiguration": {
"passRequestHeaders": boolean,
"payloadFilter": {
"exclude": [
{ ... }
]
}
},
"interceptionPoints": [ "string" ],
"interceptor": { ... }
}
],
"kmsKeyArn": "string",
"name": "string",
"policyEngineConfiguration": {
"arn": "string",
"mode": "string"
},
"protocolConfiguration": { ... },
"protocolType": "string",
"roleArn": "string",
"status": "string",
"statusReasons": [ "string" ],
"updatedAt": "string",
"wafConfiguration": {
"failureMode": "string"
},
"webAclArn": "string",
"workloadIdentityDetails": {
"workloadIdentityArn": "string"
}
}
Response Elements
If the action is successful, the service sends back an HTTP 202 response.
The following data is returned in JSON format by the service.
-
The authorizer configuration for the created gateway.
Type: AuthorizerConfiguration object
Note: This object is a Union. Only one member of this object can be specified or returned.
-
The type of authorizer used by the gateway.
Type: String
Valid Values:
CUSTOM_JWT | AWS_IAM | NONE | AUTHENTICATE_ONLY - createdAt
-
The timestamp when the gateway was created.
Type: Timestamp
- customTransformConfiguration
-
The custom transformation configuration for the gateway. This configuration defines how the gateway transforms requests and responses.
Type: CustomTransformConfiguration object
- description
-
The description of the gateway.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 200.
- domainOverride
-
The public domain names that the gateway advertises in its OAuth discovery URLs instead of the inbound Host header.
Type: DomainOverride object
- exceptionLevel
-
The level of detail in error messages returned when invoking the gateway.
-
If the value is
DEBUG, granular exception messages are returned to help a user debug the gateway. -
If the value is omitted, a generic error message is returned to the end user.
Type: String
Valid Values:
DEBUG -
- gatewayArn
-
The Amazon Resource Name (ARN) of the created gateway.
Type: String
Pattern:
arn:aws(|-cn|-us-gov):bedrock-agentcore:[a-z0-9-]{1,20}:[0-9]{12}:gateway/([0-9a-z][-]?){1,48}-[a-z0-9]{10} - gatewayId
-
The unique identifier of the created gateway.
Type: String
Pattern:
([0-9a-z][-]?){1,100}-[0-9a-z]{10} - gatewayUrl
-
The URL endpoint for the created gateway.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 1024.
- interceptorConfigurations
-
The list of interceptor configurations for the created gateway.
Type: Array of GatewayInterceptorConfiguration objects
Array Members: Minimum number of 1 item. Maximum number of 2 items.
- kmsKeyArn
-
The Amazon Resource Name (ARN) of the AWS KMS key used to encrypt data associated with the gateway.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 2048.
Pattern:
arn:aws(|-cn|-us-gov):kms:[a-zA-Z0-9-]*:[0-9]{12}:key/[a-zA-Z0-9-]{36} - name
-
The name of the gateway.
Type: String
Pattern:
([0-9a-zA-Z][-]?){1,48} - policyEngineConfiguration
-
The policy engine configuration for the created gateway.
Type: GatewayPolicyEngineConfiguration object
- protocolConfiguration
-
The configuration settings for the protocol used by the gateway.
Type: GatewayProtocolConfiguration object
Note: This object is a Union. Only one member of this object can be specified or returned.
- protocolType
-
The protocol type of the gateway.
Type: String
Valid Values:
MCP - roleArn
-
The Amazon Resource Name (ARN) of the IAM role associated with the gateway.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 2048.
Pattern:
arn:aws(-[^:]+)?:iam::([0-9]{12})?:role/.+ - status
-
The current status of the gateway.
Type: String
Valid Values:
CREATING | UPDATING | UPDATE_UNSUCCESSFUL | DELETING | READY | FAILED - statusReasons
-
The reasons for the current status of the gateway.
Type: Array of strings
Array Members: Minimum number of 0 items. Maximum number of 100 items.
Length Constraints: Minimum length of 0. Maximum length of 2048.
- updatedAt
-
The timestamp when the gateway was last updated.
Type: Timestamp
- wafConfiguration
-
The AWS WAF configuration for the gateway.
Type: WafConfiguration object
- webAclArn
-
The Amazon Resource Name (ARN) of the AWS WAF web ACL associated with the gateway.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 2048.
Pattern:
arn:[a-z0-9\-]+:wafv2:[a-z0-9\-]+:[0-9]{12}:regional/webacl/.+ - workloadIdentityDetails
-
The workload identity details for the created gateway.
Type: WorkloadIdentityDetails object
Errors
For information about the errors that are common to all actions, see Common Error Types.
- AccessDeniedException
-
This exception is thrown when a request is denied per access permissions
HTTP Status Code: 403
- ConflictException
-
This exception is thrown when there is a conflict performing an operation
HTTP Status Code: 409
- InternalServerException
-
This exception is thrown if there was an unexpected error during processing of request
HTTP Status Code: 500
- ServiceQuotaExceededException
-
This exception is thrown when a request is made beyond the service quota
HTTP Status Code: 402
- ThrottlingException
-
This exception is thrown when the number of requests exceeds the limit
HTTP Status Code: 429
- ValidationException
-
The input fails to satisfy the constraints specified by the service.
HTTP Status Code: 400
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following: