CreateGateway - Amazon Bedrock AgentCore Control
Request SyntaxURI Request ParametersRequest BodyResponse SyntaxResponse ElementsErrorsSee Also

CreateGateway

Creates a gateway for Amazon Bedrock Agent. A gateway serves as an integration point between your agent and external services.

To create a gateway, you must specify a name, protocol type, and IAM role. The role grants the gateway permission to access AWS services and resources.

Request Syntax

POST /gateways/ HTTP/1.1
Content-type: application/json

{
   "authorizerConfiguration": { ... },
   "authorizerType": "string",
   "clientToken": "string",
   "description": "string",
   "exceptionLevel": "string",
   "kmsKeyArn": "string",
   "name": "string",
   "protocolConfiguration": { ... },
   "protocolType": "string",
   "roleArn": "string"
}

URI Request Parameters

The request does not use any URI parameters.

Request Body

The request accepts the following data in JSON format.

authorizerConfiguration

The authorizer configuration for the Gateway.

Type: AuthorizerConfiguration object

Note: This object is a Union. Only one member of this object can be specified or returned.

Required: Yes

authorizerType

The type of authorizer to use for the gateway.

Type: String

Valid Values: CUSTOM_JWT

Required: Yes

clientToken

A unique, case-sensitive identifier to ensure that the operation completes no more than one time. If this token matches a previous request, Amazon Bedrock ignores the request but does not return an error.

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

exceptionLevel

The verbosity of exception messages. Use DEBUG mode to see granular exception messages from a Gateway. If this parameter is not set, exception messages are by default sanitized for presentation to end users.

Type: String

Valid Values: DEBUG

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,100}

Required: Yes

protocolConfiguration

The configuration settings for the protocol specified in the protocolType parameter.

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. Currently supports MCP (Model Context Protocol).

Type: String

Valid Values: MCP

Required: Yes

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

Response Syntax

HTTP/1.1 202
Content-type: application/json

{
   "authorizerConfiguration": { ... },
   "authorizerType": "string",
   "createdAt": "string",
   "description": "string",
   "exceptionLevel": "string",
   "gatewayArn": "string",
   "gatewayId": "string",
   "gatewayUrl": "string",
   "kmsKeyArn": "string",
   "name": "string",
   "protocolConfiguration": { ... },
   "protocolType": "string",
   "roleArn": "string",
   "status": "string",
   "statusReasons": [ "string" ],
   "updatedAt": "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.

authorizerConfiguration

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.

authorizerType

The type of authorizer used by the gateway.

Type: String

Valid Values: CUSTOM_JWT

createdAt

The timestamp when the gateway was created.

Type: Timestamp

description

The description of the gateway.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 200.

exceptionLevel

The verbosity of exception messages. Use DEBUG mode to see granular exception messages from a Gateway. If this parameter is not set, exception messages are by default sanitized for presentation to end users.

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-zA-Z]{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.

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,100}

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

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 Errors.

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: