Handling Authentication Yourself (in Automation)

If you can generate an authentication token (e.g. to use in a header or cookie) and you know that your app will not invalidate it while you are using ZAP then one option is to handle authentication yourself.

In this case you take on the responsibility for handling the authentication and session handling. This means that you do not have to configure ZAP as much but it also means that ZAP will not be able to help you as much.

Authentication Env Vars

If your app just needs one authentication token which you can generate outside of ZAP then you can use the ZAP Authentication environmental variables.

There are 3 of these env vars which are documented on the Desktop User Guide Authentication page and reproduced here for completeness:

  • ZAP_AUTH_HEADER_VALUE - if this is defined then its value will be added as a header to all of the requests
  • ZAP_AUTH_HEADER - if this is defined then its value will be used as the header name - if it is not defined then the standard Authorization header will be used
  • ZAP_AUTH_HEADER_SITE - if this is defined then the header will only be included in sites whose name includes its value

The env vars are standard operating system env vars so how you will need to set them will depend on your OS and possibly your shell. They need to be set before you start ZAP, they cannot be set once ZAP is already running.


Scripts give you complete control over all of the requests and responses that are proxied through or generated by ZAP.

If you are handling authentication yourself then HTTP Sender scripts are likely to be the most useful type.

The Community Scripts repo has a large number of HTTP Sender scripts which you can use as the basis for your own solution.

In order to use scripts in automation see the FAQ How do you add a script to ZAP from the command line?.

Replacer Rules

Replacer Rules are an easy way to replace and insert strings in requests and responses.

The easiest way to create and test them is via the Desktop UI. You can still use them in automation - see the FAQ How do you find out what key to use to set a config value on the command line? which includes an example for a Replacer rule.


If you can define a Verification Strategy for your site then you are strongly recommended to do so.

You can perform authenticated scans while still handling authentication yourself. ZAP will maintain statistics based on the Verification Strategy which will allow you to see if authentication appears to be working.

For more details see Verification strategies (Coming Soon).