Deactivate automatic contract enforcement in API Firewall

API Firewall automatically enforces the API contract spelled out in your API definition. It filters out unwanted requests, only letting through the requests that should be allowed based on the OpenAPI definition of the API it protects. API Firewall also blocks any responses from the API that have not been declared or that do not match the API definition. For more details on the validation that API Firewall performs, see How API Firewall validates API traffic.

By default, API Firewall blocks all API requests and responses that do not conform to the OpenAPI definition of the protected API. In some cases, however, you might want to deactivate the allowlist.

You can add the extension x-42c-deactivate-allowlist directly to your OpenAPI definition to control when API Firewall applies allowlist and when it does not. The extension can be added on any of the levels in your API definition, with lower levels overriding higher levels.

Deactivating automatic contract enforcement should always be done on a case-by-case basis after a careful consideration. Deactivating it in the wrong place could have serious consequences to the security of your API.

  1. Open your OpenAPI definition for editing, and go to where you want to deactivate the allowlist.
  2. Add the extension x-42c-deactivate-allowlist and set its value to true:
    # ...
    paths:
        /apis:
            get:
                x-42c-deactivate-allowlist: true
  3. To override the deactivation on another level (scope), for example, to keep API Firewall limiting what kind of API responses are send to API consumers, set x-42c-deactivate-allowlist to false:
  4. # ...
    paths:
        /apis:
            get:
                x-42c-deactivate-allowlist: true     # scope 'Operation'
                parameters:
                    # ...
                responses:
                    200:
                        x-42c-deactivate-allowlist: false   # scope 'Status'
  5. Save the API definition.

The changes take effect after you reconfigure API Firewall for the updated API. For more details, see Reconfigure API Protection.

You can find the details of the requests and responses that API Firewall blocked in the transaction logs through Trace Explorer or from the Protection tab of your API.

For more details, see Automatic contract enforcement.

Use directional allowlist protections

You might want to switch off the allowlist for all outgoing responses, but keep it on for all incoming requests, or the other way round. In this case you can combine x-42c-deactivate-allowlist with the directional allowlist protections x-42c-request-allowlist_0.1 and x-42c-response-allowlist_0.1: first you deactivate the automatic allowlist for the whole API, then you add the directional allowlist that you want like any other additional protections (see Protections and security extensions).

  1. On the top level of your API, add the extension x-42c-deactivate-allowlist and set its value to true.
  2. To keep the allowlist active for all incoming requests, add a request strategy that applies the protection x-42c-request-allowlist_0.1:
    # ...
    description: Pixi Photo Sharing API
    version: 1.0.0
    # ...
    x-42c-deactivate-allowlist: true
    # ...
    x-42c-request-strategies:
        - x-42c-strategy:
            protections:
                - x-42c-request-allowlist_0.1:
  3. If you want to activate the allowlist for a particular response, you can add a local strategy that applies the protection x-42c-response-allowlist_0.1 to it:
    # ...
    description: Pixi Photo Sharing API
    version: 1.0.0
    # ...
    x-42c-deactivate-allowlist: true
    # ...
    x-42c-request-strategies:
        - x-42c-strategy:
            protections:
                - x-42c-request-allowlist_0.1:
    # ...
    responses:
        200: 
            # ...            
            x-42c-local-strategy: 
                x-42c-strategy:
                    protections:
                        - x-42c-response-allowlist_0.1:
    
    
  4. Save the API definition.

The changes take effect after you reconfigure API Firewall for the updated API. For more details, see Reconfigure API Protection.