# Log Amazon Bedrock AgentCore Gateway API calls with CloudTrail
<a name="gateway-cloudtrail"></a>

Amazon Bedrock AgentCore Gateway is integrated with AWS CloudTrail, a service that provides a record of actions taken by a user, role, or an AWS service in Gateway. CloudTrail captures all API calls for Gateway as events, including calls from the Gateway console and code calls to the Gateway APIs. Using the information collected by CloudTrail, you can determine the request that was made to Gateway, who made the request, when it was made, and additional details. There are two types of events: **Management events** and **Data events**.

For more information about using CloudTrail with Gateway, see the following resources:
+  [AWS CloudTrail User Guide](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/) 
+  [Creating a Trail for Your AWS Account](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html) 
+  [AWS CloudTrail API Reference](https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/) 
+  [AWS CloudTrail CLI Reference](https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/index.html) 

**Topics**
+ [Amazon Bedrock AgentCore Gateway event types](gateway-event-types.md)
+ [Enable CloudTrail data event logging for Amazon Bedrock AgentCore Gateway resources](enabling-cloudtrail-data-event-logging.md)
+ [Understanding Amazon Bedrock AgentCore Gateway CloudTrail events](understanding-gateway-cloudtrail-log-entries.md)

# Amazon Bedrock AgentCore Gateway event types
<a name="gateway-event-types"></a>

This section provides information about the types of events that Amazon Bedrock AgentCore Gateway logs to CloudTrail.

**Topics**
+ [Amazon Bedrock AgentCore Gateway management events in CloudTrail](#gateway-management-events)
+ [Amazon Bedrock AgentCore Gateway data events in CloudTrail](#gateway-data-events)

## Amazon Bedrock AgentCore Gateway management events in CloudTrail
<a name="gateway-management-events"></a>

Every management event or log entry contains information about who generated the request. The identity information helps you determine the following:
+ Whether the request was made with root user or user credentials.
+ Whether the request was made on behalf of an IAM Identity Center user.
+ Whether the request was made with temporary security credentials for a role or federated user.
+ Whether the request was made by another AWS service.

CloudTrail is active in your AWS account when you create the account and you automatically have access to the CloudTrail *Event history* . The CloudTrail *Event history* provides a viewable, searchable, downloadable, and immutable record of the past 90 days of recorded management events in an AWS Region.

For an ongoing record of events in your AWS account past 90 days, create a trail or a CloudTrail Lake event data store.

Gateway logs management events for the following operations:


| Operation | Description | 
| --- | --- | 
|  CreateGateway  |  Creates a new gateway  | 
|  CreateGatewayTarget  |  Creates a new target for a gateway  | 
|  DeleteGateway  |  Deletes a gateway  | 
|  DeleteGatewayTarget  |  Deletes a gateway target  | 
|  GetGateway  |  Gets information about a gateway  | 
|  GetGatewayTarget  |  Gets information about a gateway target  | 
|  ListGatewayTargets  |  Lists all targets for a gateway  | 
|  ListGateways  |  Lists all gateways  | 
|  UpdateGateway  |  Updates an existing gateway  | 
|  UpdateGatewayTarget  |  Updates an existing gateway target  | 

## Amazon Bedrock AgentCore Gateway data events in CloudTrail
<a name="gateway-data-events"></a>

Data events provide information about the resource operations performed on or in a resource. These are also known as data plane operations. Data events are often high-volume activities. You must explicitly enable data events because they are not logged by default. The CloudTrail *Event history* doesn’t record data events.

Additional charges apply for logging data events. For more information about CloudTrail pricing, see [AWS CloudTrail Pricing](https://aws.amazon.com/cloudtrail/pricing/).

To learn how to enable logging data events for the Gateway resource types, see [Enable CloudTrail data event logging for Amazon Bedrock AgentCore Gateway resources](enabling-cloudtrail-data-event-logging.md).

The following table lists the Gateway resource types for which you can enable data events:


| Data event type | resources.type value | Data APIs logged to CloudTrail | 
| --- | --- | --- | 
|  Bedrock-AgentCore gateway  |   AWS::BedrockAgentCore::Gateway  |  InvokeGateway  | 

### Identity information in data events
<a name="identity-info-data-events"></a>

Amazon Bedrock AgentCore Gateway data events differ from standard AWS data events in how identity information is stored. Because the Data API follows the MCP protocol and uses JSON Web Token (JWT)-based authentication rather than SigV4, Amazon Bedrock AgentCore Gateway data events don’t have standard AWS identity information. Instead, identity is captured by logging specific JWT claims, including the "sub" claim.

**Note**  
We recommend that you avoid using any personally identifiable information (PII) in this field. For example, you could use a GUID or a pairwise identifier, as suggested in the [OIDC specification](http://openid.net/specs/openid-connect-core-1_0.html#SubjectIDTypes) instead of PII data like email.

### Error information in data events
<a name="error-info-data-events"></a>

Amazon Bedrock AgentCore Gateway provides error information as part of the `responseElements` field rather than as top-level `errorCode` and `errorMessage` fields. If you’re looking for specific error types such as AccessDenied events, parse through the `responseElements` field in the CloudTrail event.

### Data event routing
<a name="data-event-routing"></a>

Because Amazon Bedrock AgentCore Gateway uses JWT tokens for authentication rather than SigV4 credentials, data events are only routed to the resource owner account.

# Enable CloudTrail data event logging for Amazon Bedrock AgentCore Gateway resources
<a name="enabling-cloudtrail-data-event-logging"></a>

You can use CloudTrail data events to get information about Amazon Bedrock AgentCore Gateway requests. To enable CloudTrail data events for Gateway, you must create a trail manually in CloudTrail backed by an Amazon S3 bucket.

 **Key considerations** 
+ Data event logging incurs additional charges. You must explicitly enable data events as they are not captured by default. Check to ensure that you have data events enabled for your account.
+ With a gateway that is generating a high workload, you could quickly generate thousands of logs in a short amount of time. Be mindful of how long you choose to enable CloudTrail data events for a busy Gateway.
+ CloudTrail stores gateway data event logs in an Amazon S3 bucket of your choosing. Consider using a bucket in a separate AWS account to better organize events from multiple resources into a central place for easier querying and analysis.

When you log data events for a trail in CloudTrail, you must use advanced event selectors to log data events for gateway operations.

**Example**  

1. To enable CloudTrail data events for gateway resources using the AWS CLI, you can run the following command in a terminal:

   ```
   aws cloudtrail put-event-selectors \
     --trail-name brac-gateway-canary-trail-prod-us-east-1 \
     --region us-east-1 \
     --advanced-event-selectors '[
       {
         "Name": "GatewayDataEvents",
         "FieldSelectors": [
           {
             "Field": "eventCategory",
             "Equals": ["Data"]
           },
           {
             "Field": "resources.type",
             "Equals": ["AWS::BedrockAgentCore::Gateway"]
           }
         ]
       }
     ]'
   ```

1. The following example demonstrates how to create a CloudTrail trail with AgentCore Gateway data events using the AWS CDK:

   ```
   import { Construct } from 'constructs';
   import { Trail, CfnTrail } from 'aws-cdk-lib/aws-cloudtrail';
   import { Bucket } from 'aws-cdk-lib/aws-s3';
   import { Effect, PolicyStatement, ServicePrincipal } from 'aws-cdk-lib/aws-iam';
   import { RemovalPolicy } from 'aws-cdk-lib';
   
   export interface DataEventTrailProps {
     /**
      * Whether to enable multi-region trail
      */
     isMultiRegionTrail?: boolean;
   
     /**
      * Whether to include global service events
      */
     includeGlobalServiceEvents?: boolean;
   
     /**
      * AWS region
      */
     region: string;
   
     /**
      * Environment account ID
      */
     account: string;
   }
   
   /**
    * Creates a CloudTrail trail configured to capture data events for Bedrock Agent Core Gateway
    */
   export class BedrockAgentCoreDataEventTrail extends Construct {
     /**
      * The CloudTrail trail
      */
     public readonly trail: Trail;
   
     /**
      * The S3 bucket for CloudTrail logs
      */
     public readonly logsBucket: Bucket;
   
     constructor(scope: Construct, id: string, props: DataEventTrailProps) {
       super(scope, id);
   
       // Create S3 bucket for CloudTrail logs
       const bucketName = `brac-gateway-cloudtrail-logs-${props.account}-${props.region}`;
       this.logsBucket = new Bucket(this, 'CloudTrailLogsBucket', {
         bucketName,
         removalPolicy: RemovalPolicy.RETAIN,
       });
   
       // Create trail name (suffixing region since regional trail)
       const trailName = `brac-gateway-trail-${props.region}`;
   
       // Add CloudTrail bucket policy
       this.logsBucket.addToResourcePolicy(
         new PolicyStatement({
           sid: 'AWSCloudTrailAclCheck',
           effect: Effect.ALLOW,
           principals: [new ServicePrincipal('cloudtrail.amazonaws.com')],
           actions: ['s3:GetBucketAcl'],
           resources: [this.logsBucket.bucketArn],
           conditions: {
             StringEquals: {
               'aws:SourceArn': `arn:aws:cloudtrail:${props.region}:${props.account}:trail/${trailName}`,
             },
           },
         }),
       );
   
       this.logsBucket.addToResourcePolicy(
         new PolicyStatement({
           sid: 'AWSCloudTrailWrite',
           effect: Effect.ALLOW,
           principals: [new ServicePrincipal('cloudtrail.amazonaws.com')],
           actions: ['s3:PutObject'],
           resources: [this.logsBucket.arnForObjects(`AWSLogs/${props.account}/*`)],
           conditions: {
             StringEquals: {
               's3:x-amz-acl': 'bucket-owner-full-control',
               'aws:SourceArn': `arn:aws:cloudtrail:${props.region}:${props.account}:trail/${trailName}`,
             },
           },
         }),
       );
   
       // Create CloudTrail trail
       this.trail = new Trail(this, 'GatewayDataEventTrail', {
         trailName,
         bucket: this.logsBucket,
         isMultiRegionTrail: props.isMultiRegionTrail ?? false,
         includeGlobalServiceEvents: props.includeGlobalServiceEvents ?? true,
         enableFileValidation: true,
       });
   
       // Add advanced event selectors for Bedrock Agent Core Gateway data events
       const cfnTrail = this.trail.node.defaultChild as CfnTrail;
   
       // Define the advanced event selectors
       const advancedEventSelectors = [
         {
           // Log Bedrock Agent Core Gateway Data Events only
           fieldSelectors: [
             {
               field: 'eventCategory',
               equalTo: ['Data'],
             },
             {
               field: 'resources.type',
               equalTo: ['AWS::BedrockAgentCore::Gateway'],
             },
           ],
         },
       ];
   
       // Clear any existing event selectors and set advanced event selectors
       cfnTrail.eventSelectors = undefined;
       cfnTrail.advancedEventSelectors = advancedEventSelectors;
     }
   }
   ```

# Understanding Amazon Bedrock AgentCore Gateway CloudTrail events
<a name="understanding-gateway-cloudtrail-log-entries"></a>

A trail is a configuration that enables delivery of events as log files to an Amazon S3 bucket that you specify. CloudTrail log files contain one or more log entries. An event represents a single request from any source and includes information such as the requested action, the date and time of the action, and request parameters.

**Note**  
The contents of the requests and responses for data events are redacted, and the JSON Web Token (JWT) claims have HTML entities sanitized for security purposes.

The following sections show examples of CloudTrail events:

**Topics**
+ [InvokeGateway data event with authentication error](#understanding-gateway-cloudtrail-log-entries-data-auth-error)
+ [Successful InvokeGateway data event](#understanding-gateway-cloudtrail-log-entries-data-successful)
+ [Management Event](#understanding-gateway-cloudtrail-log-entries-management)

## InvokeGateway data event with authentication error
<a name="understanding-gateway-cloudtrail-log-entries-data-auth-error"></a>

The following example shows a CloudTrail log entry that demonstrates the `InvokeGateway` action with an authentication error. The authentication error can be seen in hte `body` field of the `responseElements`.

```
{
  "eventVersion": "1.11",
  "userIdentity": {
    "type": "AWSAccount",
    "principalId": "",
    "accountId": "anonymous"
  },
  "eventTime": "2025-07-14T02:14:42Z",
  "eventSource": "bedrock-agentcore.amazonaws.com",
  "eventName": "InvokeGateway",
  "awsRegion": "us-west-2",
  "sourceIPAddress": "34.XXX.XXX.206",
  "userAgent": "python-httpx/0.28.1",
  "requestParameters": {
    "body": {
      "id": 0,
      "method": "initialize",
      "params": {
        "clientInfo": {
          "name": "mcp",
          "version": "0.1.0"
        },
        "protocolVersion": "2025-06-18",
        "capabilities": {}
      },
      "jsonrpc": "2.0"
    }
  },
  "responseElements": {
    "body": {
      "jsonrpc": "2.0",
      "id": 0,
      "error": {
        "code": -32001,
        "message": "Invalid Bearer token"
      }
    },
    "contentType": "application/json",
    "statusCode": 401
  },
  "requestID": "1234abcd-12ab-34cd-56ef-1234567890ab",
  "eventID": "12345678-1234-5678-9abc-123456789012",
  "readOnly": false,
  "resources": [
    {
      "accountId": "XXXXXXXXXX",
      "type": "AWS::BedrockAgentCore::Gateway",
      "ARN": "arn:aws:bedrock-agentcore:us-west-2:XXXXXXXXXX:gateway/test-openapi-gateway-b24f8c26-u9p3rjw8qw"
    }
  ],
  "eventType": "AwsApiCall",
  "managementEvent": false,
  "recipientAccountId": "XXXXXXXXXX",
  "sharedEventID": "12345678-xxxx-xxxx-xxxx-123456789012",
  "eventCategory": "Data",
  "tlsDetails": {
    "tlsVersion": "TLSv1.2",
    "cipherSuite": "ECDHE-RSA-AES128-GCM-SHA256",
    "clientProvidedHostHeader": "test-openapi-gateway-xxxxxxx-u9p3rjw8qw.gateway.bedrock-agentcore.us-west-2.amazonaws.com"
  }
}
```

## Successful InvokeGateway data event
<a name="understanding-gateway-cloudtrail-log-entries-data-successful"></a>

The following example shows a CloudTrail log entry for a successful `InvokeGateway` action:

```
{
      "eventVersion": "1.11",
      "userIdentity": {
        "type": "AWSAccount",
        "principalId": "",
        "accountId": "anonymous"
      },
      "eventTime": "2025-07-14T02:14:42Z",
      "eventSource": "bedrock-agentcore.amazonaws.com",
      "eventName": "InvokeGateway",
      "awsRegion": "us-west-2",
      "sourceIPAddress": "35.88.103.184",
      "userAgent": "python-httpx/0.28.1",
      "requestParameters": {
        "body": {
          "id": 1,
          "method": "tools/call",
          "params": {
            "name": "SmithyTarget___ListTables",
            "arguments": "REDACTED"
          },
          "jsonrpc": "2.0"
        }
      },
      "responseElements": {
        "body": {
          "jsonrpc": "2.0",
          "id": 1,
          "result": {
            "isError": false,
            "content": "REDACTED"
          }
        },
        "contentType": "application/json",
        "statusCode": 200
      },
      "additionalEventData": {
        "targetId": "0JTXXX4YMA",
        "jwt": {
          "headers": {
            "kid": "hGrcJwz5MX6hNeuL6jdXE4hjK7sT6oj+yN7kN+arRv4=",
            "alg": "RS256"
          },
          "claims": {
            "sub": "4ammgxxxxxxxxxxxm3b8c",
            "token_use": "access",
            "scope": "python-cognito-resource-server-id/write python-cognito-resource-server-id/read",
            "auth_time": 1752459276,
            "iss": "https://cognito-idp.us-west-2.amazonaws.com/us-west-2_Fxxxxxhtq",
            "exp": 1752462876,
            "iat": 1752459276,
            "version": 2,
            "jti": "1234abcd-12ab-34cd-56ef-1234567890ab"
          },
          "type": "JWS"
        },
        "downstreamRequestIds": [
          "H3RDH6T03DG10996U0M2P1V1IFVV4KQNSO5AEMVJF66Q9ASUAAJG"
        ]
      },
      "requestID": "1234abcd-12ab-34cd-56ef-1234567890ab",
      "eventID": "12345678-1234-5678-9abc-123456789012",
      "readOnly": false,
      "resources": [
        {
          "accountId": "XXXXXXXXXX",
          "type": "AWS::BedrockAgentCore::Gateway",
          "ARN": "arn:aws:bedrock-agentcore:us-west-2:XXXXXXXXXX:gateway/test-gateway-65129e91-mtzoadyihf"
        }
      ],
      "eventType": "AwsApiCall",
      "managementEvent": false,
      "recipientAccountId": "XXXXXXXXXX",
      "sharedEventID": "1234abcd-12ab-34cd-56ef-1234567890ab",
      "eventCategory": "Data",
      "tlsDetails": {
        "tlsVersion": "TLSv1.2",
        "cipherSuite": "ECDHE-RSA-AES128-GCM-SHA256",
        "clientProvidedHostHeader": "test-gateway-65129e91-xxxxxxxx.gateway.bedrock-agentcore.us-west-2.amazonaws.com"
      }
    }
```

## Management Event
<a name="understanding-gateway-cloudtrail-log-entries-management"></a>

The following example shows a CloudTrail log entry for a management event:

```
{
  "eventVersion": "1.09",
  "userIdentity": {
    "type": "AssumedRole",
    "principalId": "AROXXXXXXXXXXXXNRD7D:xxxxx",
    "arn": "arn:aws:sts::XXXXXXXXXXXX:assumed-role/HydraInvocationRole-xxxxxxxxx/xxxx",
    "accountId": "XXXXXXXXXXXX",
    "accessKeyId": "xxxxxxxxx",
    "sessionContext": {
      "sessionIssuer": {
        "type": "Role",
        "principalId": "xxxxxxxx",
        "arn": "arn:aws:iam::XXXXXXXXXXXX:role/HydraInvocationRole-xxx",
        "accountId": "XXXXXXXXXXXX",
        "userName": "HydraInvocationRole-xxxxx"
      },
      "attributes": {
        "creationDate": "2025-07-14T02:42:43Z",
        "mfaAuthenticated": "false"
      }
    },
    "invokedBy": "bedrock-agentcore.amazonaws.com"
  },
  "eventTime": "2025-07-14T02:47:38Z",
  "eventSource": "bedrock-agentcore.amazonaws.com",
  "eventName": "CreateGateway",
  "awsRegion": "us-west-2",
  "sourceIPAddress": "bedrock-agentcore.amazonaws.com",
  "userAgent": "bedrock-agentcore.amazonaws.com",
  "requestParameters": {
    "roleArn": "arn:aws:iam::XXXXXXXXXXXX:role/PythonGenesisTestGatewayRole",
    "name": "***",
    "authorizerConfiguration": {
      "customJWTAuthorizer": {
        "allowedClients": [
          "xxxxxxxxx"
        ],
        "discoveryUrl": "https://cognito-idp.us-west-2.amazonaws.com/us-west-2_xxxxx/.well-known/openid-configuration"
      }
    },
    "description": "***",
    "protocolType": "MCP",
    "authorizerType": "CUSTOM_JWT"
  },
  "responseElements": {
    "authorizerConfiguration": {
      "customJWTAuthorizer": {
        "allowedClients": [
          "xxxxxxxxxxxxxxx"
        ],
        "discoveryUrl": "https://cognito-idp.us-west-2.amazonaws.com/us-west-2_xxxxxx/.well-known/openid-configuration"
      }
    },
    "description": "***",
    "protocolType": "MCP",
    "gatewayArn": "arn:aws:bedrock-agentcore:us-west-2:XXXXXXXXXXXX:gateway/test-openapi-gateway-xxxxxxx-xxxxxx",
    "workloadIdentityDetails": {
      "workloadIdentityArn": "arn:aws:bedrock-agentcore:us-west-2:XXXXXXXXXXXX:workload-identity-directory/default/workload-identity/test-openapi-gateway-xxxxxx-xxxxx"
    },
    "createdAt": "2025-07-14T02:47:38.302834063Z",
    "gatewayUrl": "https://test-openapi-gateway-xxxxxxx-8fb4mo6pqx.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp",
    "roleArn": "arn:aws:iam::XXXXXXXXXXXX:role/PythonGenesisTestGatewayRole",
    "name": "***",
    "authorizerType": "CUSTOM_JWT",
    "gatewayId": "test-openapi-gateway-9c8f7109-8fb4mo6pqx",
    "status": "CREATING",
    "updatedAt": "2025-07-14T02:47:38.302845797Z"
  },
  "requestID": "0fb99b0b-a4d1-xxxx-8aee-c703adaa6bd9",
  "eventID": "b12bf859-xxxx-48d7-952a-d5c6ec00fb68",
  "readOnly": false,
  "resources": [
    {
      "accountId": "XXXXXXXXXXXX",
      "type": "AWS::BedrockAgentCore::Gateway",
      "ARN": "arn:aws:bedrock-agentcore:us-west-2:XXXXXXXXXXXX:gateway/test-openapi-gateway-xxxxxxx-8fb4mo6pqx"
    }
  ],
  "eventType": "AwsApiCall",
  "managementEvent": true,
  "recipientAccountId": "XXXXXXXXXXXX",
  "eventCategory": "Management"
}
```