CreateGateway - Amazon Bedrock AgentCore Control Plane
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.

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",
   "exceptionLevel": "string",
   "kmsKeyArn": "string",
   "name": "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.

authorizerConfiguration

The authorizer configuration for the gateway. Required if authorizerType is CUSTOM_JWT.

Type: AuthorizerConfiguration object

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

Required: No

authorizerType

The type of authorizer to use for the gateway.

  • CUSTOM_JWT - Authorize with a bearer token.

  • AWS_IAM - Authorize with your AWS IAM credentials.

Type: String

Valid Values: CUSTOM_JWT | AWS_IAM

Required: 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

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

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.

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

tags

A map of key-value pairs to associate with the gateway as metadata tags.

Type: String to string map

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",
   "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 | AWS_IAM

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 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-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: