# Use policies
Use policies

This section explains how to create and manage Cedar policies.

**Topics**
+ [

# Add policies to the Policy Engine
](add-policies-to-engine.md)
+ [

# Create gateway with Policy Engine
](create-gateway-with-policy.md)
+ [

# Update existing gateway with Policy Engine
](update-gateway-with-policy.md)
+ [

# Policy enforcement modes
](policy-enforcement-modes.md)
+ [

# Use an AgentCore Gateway with Policy in AgentCore
](use-gateway-with-policy.md)
+ [

# Manage Policies and Policy Engines
](manage-policies-engines.md)
+ [

# Errors
](policy-use-errors.md)

# Add policies to the Policy Engine
Add policies to the Policy Engine

You can create one or more policies in your policy engine to control how agents interact with your enterprise tools and data through Amazon Bedrock AgentCore Gateway.

**Note**  
Use the policy engine ID from the previous step. The validation mode determines how policy validation findings are handled: `FAIL_ON_ANY_FINDINGS` will reject policies with validation issues, while `IGNORE_ALL_FINDINGS` will accept them. For more information about validation and the types of findings, see [Validate and test policies](policy-validate-policies.md).

Select one of the following methods:

**Example**  

1. Run the following code in a terminal to create a policy using the AWS CLI:

   ```
   aws bedrock-agentcore-control create-policy \
     --policy-engine-id my-policy-engine-id \
     --name my_policy \
     --validation-mode FAIL_ON_ANY_FINDINGS \
     --description "My Policy" \
     --definition '{
       "cedar": {
         "statement": "my-cedar-policy-statement"
       }
     }'
   ```

1. The following Python code shows how to create a policy using the AWS Python SDK (Boto3):

   ```
   import boto3
   
   client = boto3.client('bedrock-agentcore-control')
   
   response = client.create_policy(
       policyEngineId='my-policy-engine-id',
       name='my_policy',
       validationMode='FAIL_ON_ANY_FINDINGS',
       description='My Policy',
       definition={
           'cedar': {
               'statement': 'my-cedar-policy-statement'
           }
       }
   )
   print(f"Policy ID: {response['policyId']}")
   ```

# Create gateway with Policy Engine
Create gateway with Policy Engine

This section provides examples of creating a gateway with a policy engine associated for policy enforcement.

**Note**  
\$1 The values for the authorization configuration are from when you set up inbound authorization. \$1 If you choose an option that involves specifying an overt gateway service role ARN, ensure that you specify an existing one that you’ve set up. For more information, see Amazon Bedrock AgentCore Gateway service role permissions.

Select one of the following methods:

**Example**  

1. Run the following code in a terminal to create a gateway with a Policy Engine using the AWS CLI:

   ```
   aws bedrock-agentcore-control create-gateway \
     --name my-gateway \
     --role-arn arn:aws:iam::123456789012:role/my-gateway-service-role \
     --protocol-type MCP \
     --authorizer-type CUSTOM_JWT \
     --authorizer-configuration '{
       "customJWTAuthorizer": {
         "discoveryUrl": "https://cognito-idp.us-west-2.amazonaws.com/some-user-pool/.well-known/openid-configuration",
         "allowedClients": ["clientId"]
       }
     }' \
     --policy-engine-configuration '{
       "mode": "ENFORCE",
       "arn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:policy-engine/my_policy_engine"
     }'
   ```

   The gatewayUrl in the response is the endpoint to use when you invoke the gateway.

1. The following Python code shows how to create a gateway with a Policy Engine using the AWS Python SDK (Boto3):

   ```
   import boto3
   
   gateway_client = boto3.client('bedrock-agentcore-control')
   
   response = gateway_client.create_gateway(
       name='my-gateway',
       protocolType='MCP',
       authorizerType='CUSTOM_JWT',
       authorizerConfiguration={
           'customJWTAuthorizer': {
               'allowedClients': ['clientId'],
               'discoveryUrl': 'https://cognito-idp.us-west-2.amazonaws.com/some-user-pool/.well-known/openid-configuration'
           }
       },
       roleArn='arn:aws:iam::123456789012:role/my-gateway-service-role',
       policyEngineConfiguration={
           'mode': 'ENFORCE',
           'arn': 'arn:aws:bedrock-agentcore:us-west-2:123456789012:policy-engine/my_policy_engine'
       }
   )
   print(f"GATEWAY ARN: {response['gatewayArn']}")
   print(f"GATEWAY URL: {response['gatewayUrl']}")
   ```

   The gatewayUrl in the response is the endpoint to use when you invoke the gateway.

# Update existing gateway with Policy Engine
Update existing gateway with Policy Engine

Associate a policy engine with an existing gateway:

**Example**  

1. Run the following code in a terminal to update a gateway with a Policy Engine using the AWS CLI:

   ```
   aws bedrock-agentcore-control update-gateway \
     --gateway-identifier my-gateway-id \
     --role-arn arn:aws:iam::123456789012:role/my-gateway-service-role \
     --protocol-type MCP \
     --authorizer-type CUSTOM_JWT \
     --authorizer-configuration '{
       "customJWTAuthorizer": {
         "discoveryUrl": "https://cognito-idp.us-west-2.amazonaws.com/some-user-pool/.well-known/openid-configuration",
         "allowedClients": ["clientId"]
       }
     }' \
     --policy-engine-configuration '{
       "mode": "ENFORCE",
       "arn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:policy-engine/my_policy_engine"
     }'
   ```

   The gatewayUrl in the response is the endpoint to use when you invoke the gateway.

1. The following Python code shows how to update a gateway with a Policy Engine using the AWS Python SDK (Boto3):

   ```
   import boto3
   
   gateway_client = boto3.client('bedrock-agentcore-control')
   
   response = gateway_client.update_gateway(
       name='my-gateway-name',
       gatewayId='my-gateway-id',
       protocolType='MCP',
       authorizerType='CUSTOM_JWT',
       authorizerConfiguration={
           'customJWTAuthorizer': {
               'allowedClients': ['clientId'],
               'discoveryUrl': 'https://cognito-idp.us-west-2.amazonaws.com/some-user-pool/.well-known/openid-configuration'
           }
       },
       roleArn='arn:aws:iam::123456789012:role/my-gateway-service-role',
       policyEngineConfiguration={
           'mode': 'ENFORCE',
           'arn': 'arn:aws:bedrock-agentcore:us-west-2:123456789012:policy-engine/my_policy_engine'
       }
   )
   
   print(f"GATEWAY ARN: {response['gatewayArn']}")
   print(f"GATEWAY URL: {response['gatewayUrl']}")
   ```

   The gatewayUrl in the response is the endpoint to use when you invoke the gateway.

# Policy enforcement modes
Policy enforcement modes

Enforcement mode defines how the gateway applies policy decisions. The policy engine supports two modes:
+ In `LOG_ONLY` mode, the policy engine evaluates and logs whether the action is would be allowed or denied without enforcing the the decision
+ In `ENFORCE` mode, the policy engine evaluates the action and enforces decisions by allowing or denying agent operations.

# Use an AgentCore Gateway with Policy in AgentCore
Use an AgentCore Gateway with Policy in AgentCore

Follow the gateway authorization and authentication guide to obtain the credentials needed for gateway access.

**Topics**
+ [

## List AgentCore Gateway Tools with Policy in AgentCore
](#list-gateway-tools)
+ [

## Call gateway tools with policy
](#call-gateway-tools)
+ [

## Policy responses
](#policy-responses)

## List AgentCore Gateway Tools with Policy in AgentCore


Tool listing is treated as a **meta action** . When a principal lists available tools, the policy engine does not evaluate the full context of a specific tool invocation (for example, input parameters).

A principal is only allowed to see tools in the listing that they would be permitted to call by policy. Because the full context of a tool call is not available during listing, this means a principal is allowed to list a tool **if there exists any set of circumstances under which a call to that tool would be permitted**.

As a result, a tool appearing in the list does not guarantee that a subsequent call to that tool will be authorized. The authorization decision for an actual tool invocation is evaluated separately using the full request context, including input parameters.

Select one of the following methods:

**Example**  

1. 

   ```
   curl -X POST \
     https://mygateway-abcdefghij.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -d '{
       "jsonrpc": "2.0",
       "id": "list-tools-request",
       "method": "tools/list"
     }'
   ```

1. 

   ```
   import requests
   import json
   
   def list_tools(gateway_url, access_token):
       headers = {
           "Content-Type": "application/json",
           "Authorization": f"Bearer {access_token}"
       }
   
       payload = {
           "jsonrpc": "2.0",
           "id": "list-tools-request",
           "method": "tools/list"
       }
   
       response = requests.post(gateway_url, headers=headers, json=payload)
       return response.json()
   
   # Example usage
   gateway_url = "https://mygateway-abcdefghij.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp"
   access_token = "YOUR_ACCESS_TOKEN"
   tools = list_tools(gateway_url, access_token)
   print(json.dumps(tools, indent=2))
   ```

   The response returns only the tools that your policies allow you to see. Tools that are denied by policies will not appear in the list.

## Call gateway tools with policy


Make tool calls to your gateway. Policy evaluation determines whether the call is allowed or denied.

Select one of the following methods:

**Example**  

1. 

   ```
   # Call a tool to test policy enforcement
   curl -X POST \
     https://mygateway-abcdefghij.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -d '{
       "jsonrpc": "2.0",
       "id": "test-policy",
       "method": "tools/call",
       "params": {
         "name": "tool_name",
         "arguments": {arguments}
       }
     }'
   ```

1. 

   ```
   import requests
   import json
   
   def call_gateway_tool(gateway_url, access_token, tool_name, arguments):
       headers = {
           "Content-Type": "application/json",
           "Authorization": f"Bearer {access_token}"
       }
   
       payload = {
           "jsonrpc": "2.0",
           "id": "test-policy",
           "method": "tools/call",
           "params": {
               "name": tool_name,
               "arguments": arguments
           }
       }
   
       response = requests.post(gateway_url, headers=headers, json=payload)
       return response.json()
   
   # Example usage
   gateway_url = "https://mygateway-abcdefghij.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp"
   access_token = "YOUR_ACCESS_TOKEN"
   result = call_gateway_tool(
       gateway_url,
       access_token,
       "RefundTool__process_refund",
       {
           "orderId": "12345",
           "amount": 450,
           "reason": "Defective product"
       }
   )
   print(json.dumps(result, indent=2))
   ```

## Policy responses


When a policy allows the request:

```
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "isError": false,
    "content": [
      {
        "type": "text",
        "text": "ToolResult"
      }
    ]
  }
}
```

When a policy denies the request:

```
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "AuthorizeActionException - Tool Execution Denied: Tool call not allowed due to policy enforcement [No policy applies to the request (denied by default).]"
      }
    ],
    "isError": true
  }
}
```

# Manage Policies and Policy Engines
Manage Policies and Policy Engines

Use these operations to manage your Policy Engines and policies.

**Topics**
+ [

## List Policy Engines
](#list-policy-engines)
+ [

## Get Policy Engine
](#get-policy-engine)
+ [

## List policies in a Policy Engine
](#list-policies-in-engine)
+ [

## Get Policy
](#get-policy)
+ [

## Update existing policies
](#update-existing-policies)
+ [

## Delete policies
](#delete-policies)
+ [

## Delete Policy Engine
](#delete-policy-engine)

## List Policy Engines


View all Policy Engines in your account.

Select one of the following methods:

**Example**  

1. 

   ```
   aws bedrock-agentcore-control list-policy-engines
   ```

1. 

   ```
   import boto3
   
   client = boto3.client('bedrock-agentcore-control')
   
   response = client.list_policy_engines()
   for engine in response['policyEngines']:
       print(f"Policy Engine: {engine['name']} (ID: {engine['policyEngineId']})")
       print(f"Status: {engine['status']}")
       print(f"Created: {engine['createdAt']}")
       print(f"ARN: {engine['policyEngineArn']}")
   ```

## Get Policy Engine


Retrieve detailed information about a specific Policy Engine:

**Example**  

1. 

   ```
   aws bedrock-agentcore-control get-policy-engine --policy-engine-id my-policy-engine-id
   ```

1. 

   ```
   import boto3
   
   client = boto3.client('bedrock-agentcore-control')
   
   response = client.get_policy_engine(
       policyEngineId='my-policy-engine-id'
   )
   
   print(f"Policy Engine: {response['name']}")
   print(f"ID: {response['policyEngineId']}")
   print(f"ARN: {response['policyEngineArn']}")
   print(f"Status: {response['status']}")
   print(f"Created: {response['createdAt']}")
   print(f"Updated: {response['updatedAt']}")
   ```

## List policies in a Policy Engine


View all policies within a specific Policy Engine:

**Example**  

1. 

   ```
   aws bedrock-agentcore-control list-policies --policy-engine-id my-policy-engine-id
   ```

1. 

   ```
   import boto3
   
   client = boto3.client('bedrock-agentcore-control')
   
   response = client.list_policies(
       policyEngineId='my-policy-engine-id'
   )
   
   for policy in response['policies']:
       print(f"Policy: {policy['name']} (ID: {policy['policyId']})")
       print(f"Status: {policy['status']}")
       print(f"Description: {policy.get('description', 'No description')}")
       print(f"Created: {policy['createdAt']}")
   ```

## Get Policy


Retrieve detailed information about a specific policy:

**Example**  

1. 

   ```
   aws bedrock-agentcore-control get-policy --policy-engine-id my-policy-engine-id --policy-id my-policy-id
   ```

1. 

   ```
   import boto3
   
   client = boto3.client('bedrock-agentcore-control')
   
   response = client.get_policy(
       policyId='my-policy-id',
       policyEngineId='my-policy-engine-id'
   )
   
   print(f"Policy: {response['name']}")
   print(f"ID: {response['policyId']}")
   print(f"ARN: {response['policyArn']}")
   print(f"Status: {response['status']}")
   print(f"Created: {response['createdAt']}")
   print(f"Updated: {response['updatedAt']}")
   print(f"Cedar Statement: {response['definition']['cedar']['statement']}")
   ```

## Update existing policies


Update a policy’s definition.

**Example**  

1. 

   ```
   aws bedrock-agentcore-control update-policy \
     --policy-id my-policy-id \
     --policy-engine-id my-policy-engine-id \
     --definition '{
       "cedar": {
         "statement": "permit(principal, action, resource);"
       }
     }'
   ```

1. 

   ```
   import boto3
   
   client = boto3.client('bedrock-agentcore-control')
   
   client.update_policy(
       policyId='my-policy-id',
       policyEngineId='my-policy-engine-id',
       definition={
           'cedar': {
               'statement': 'permit(principal, action, resource);'
           }
       }
   )
   
   waiter = client.get_waiter('policy_active')
   waiter.wait(PolicyEngineId="my-policy-engine-id", PolicyId="my-policy-id")
   ```

## Delete policies


Delete a policy from the Policy Engine.

**Example**  

1. 

   ```
   aws bedrock-agentcore-control delete-policy --policy-engine-id my-policy-engine-id --policy-id my-policy-id
   ```

1. 

   ```
   import boto3
   
   client = boto3.client('bedrock-agentcore-control')
   
   client.delete_policy(policyId='my-policy-id', policyEngineId='my-policy-engine-id')
   waiter = client.get_waiter('policy_deleted')
   waiter.wait(PolicyEngineId="my-policy-engine-id", PolicyId="my-policy-id")
   ```

## Delete Policy Engine


Delete an entire Policy Engine and all its policies.

**Note**  
\$1 You cannot delete a Policy Engine that is currently attached to a gateway. First detach it by updating the gateway configuration. \$1 You cannot delete a Policy Engine that has policies in it. First delete all the policies and then delete the engine

**Example**  

1. 

   ```
   aws bedrock-agentcore-control delete-policy-engine --policy-engine-id my-policy-engine-id
   ```

1. 

   ```
   import boto3
   
   client = boto3.client('bedrock-agentcore-control')
   
   client.delete_policy_engine(policyEngineId='my-policy-engine-id')
   ```

# Errors
Errors

Policy in AgentCore operations can return the following types of errors:

AuthorizationError  
The policy engine denied the request.  
HTTP Status Code: 403

AccessDeniedException  
You don’t have permission to perform this operation.  
HTTP Status Code: 403

ConflictException  
The request conflicts with the current state of the resource (e.g., policy name already exists).  
HTTP Status Code: 409

InternalServerException  
An internal server error occurred.  
HTTP Status Code: 500

ResourceNotFoundException  
The specified policy or policy engine does not exist.  
HTTP Status Code: 404

ServiceQuotaExceededException  
You have exceeded the service quota for policies or policy engines.  
HTTP Status Code: 402

ThrottlingException  
The request was throttled due to too many requests.  
HTTP Status Code: 429

ValidationException  
The request contains invalid parameters or the policy statement contains syntax errors.  
HTTP Status Code: 400