> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Policy Stage Configuration

> Turn policy evaluation off per stage for a Resource or a Connector

## Overview

A policy stage configuration turns off policy evaluation at one or more stages for a single Resource or Connector. Use it to roll out policies one stage at a time, or to exempt a Resource without editing every policy.

Each configuration has three switches:

| Field | Type | Default | Effect when `true` |
| - | - | - | - |
| `disable_session_policy_evaluation` | **Boolean** | `false` | Skips all `session` rules |
| `disable_request_policy_evaluation` | **Boolean** | `false` | Skips all `request` rules |
| `disable_response_policy_evaluation` | **Boolean** | `false` | Skips all `response` rules |

A skipped stage enforces nothing and records no triggered policies. Policies stay active everywhere else.

<Warning>
  Connectors currently apply stage configurations to **S3** Resources only.
  Every other technology evaluates all stages, whatever the configuration says.
</Warning>

## Scope and Precedence

A configuration targets exactly one Resource or one Connector. Each Resource and each Connector can have at most one configuration.

When a Connector handles traffic for a Resource, it looks for a configuration in this order:

1. The configuration for the Resource
2. The configuration for the Connector
3. No configuration: every stage is evaluated

Formal uses the first configuration it finds, as a whole. It does not merge switches from the Resource and Connector configurations.

## Manage Configurations

Stage configurations are managed through the API. The Control Plane and the Terraform provider don't expose them yet.

<Steps>
  <Step title="Create a configuration">
    Set `resource_id` or `connector_id`, plus the stages to turn off:

    ```bash theme={"languages":{"custom":["/languages/cel.json","/languages/rego.json"]}}
    curl -X POST "https://api.joinformal.com/core.v1.PoliciesService/CreatePolicyStageConfiguration" \
      -H "X-API-KEY: <YOUR_API_KEY>" \
      -H "Content-Type: application/json" \
      -d '{
        "resource_id": "<RESOURCE_ID>",
        "disable_response_policy_evaluation": true
      }'
    ```

    The response contains the configuration and its `id`.
  </Step>

  <Step title="List configurations">
    ```bash theme={"languages":{"custom":["/languages/cel.json","/languages/rego.json"]}}
    curl -X POST "https://api.joinformal.com/core.v1.PoliciesService/ListPolicyStageConfigurations" \
      -H "X-API-KEY: <YOUR_API_KEY>" \
      -H "Content-Type: application/json" \
      -d '{"limit": 100}'
    ```

    **Verify:** the new configuration appears with the expected switches.
  </Step>

  <Step title="Update a configuration">
    Send only the switches you want to change:

    ```bash theme={"languages":{"custom":["/languages/cel.json","/languages/rego.json"]}}
    curl -X POST "https://api.joinformal.com/core.v1.PoliciesService/UpdatePolicyStageConfiguration" \
      -H "X-API-KEY: <YOUR_API_KEY>" \
      -H "Content-Type: application/json" \
      -d '{
        "id": "<CONFIGURATION_ID>",
        "disable_response_policy_evaluation": false
      }'
    ```

    `UpdatePolicyStageConfigurationV2` replaces the whole object instead.
  </Step>

  <Step title="Delete a configuration">
    ```bash theme={"languages":{"custom":["/languages/cel.json","/languages/rego.json"]}}
    curl -X POST "https://api.joinformal.com/core.v1.PoliciesService/DeletePolicyStageConfiguration" \
      -H "X-API-KEY: <YOUR_API_KEY>" \
      -H "Content-Type: application/json" \
      -d '{"id": "<CONFIGURATION_ID>"}'
    ```

    After deletion, every stage is evaluated again, unless a Connector configuration still applies.
  </Step>
</Steps>

Connectors receive changes without a restart. See the [API reference](/docs/api/introduction) for the full request and response schemas.

## Example: Roll Out S3 Masking

To activate a new S3 policy one stage at a time:

1. Create a configuration for the S3 Resource with `disable_response_policy_evaluation` set to `true`.
2. Activate the policy and confirm that its `session` and `request` rules behave as expected in [Logs](https://app.formal.ai/logs).
3. Update the configuration to set `disable_response_policy_evaluation` to `false`.
4. Download a CSV object and confirm the masked columns.

## Troubleshooting

<AccordionGroup>
  <Accordion title="A stage still evaluates after you turned it off">
    **Cause:** The Resource is not an S3 Resource, or a Resource configuration overrides the Connector one. **Fix:** Check the technology, then list configurations and look for one with the Resource's ID.
  </Accordion>

  <Accordion title="Creating a configuration fails">
    **Cause:** The Resource or Connector already has a configuration. **Fix:** Update the existing configuration instead.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Operations" icon="wrench" href="/docs/guides/policies/operations">
    Test, roll out, and troubleshoot policies
  </Card>

  <Card title="S3" icon="aws" href="/docs/guides/core-concepts/resources/s3">
    Protect S3 buckets with Formal
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.