**Introducing a new console experience for AWS WAF**
You can now use the updated experience to access AWS WAF functionality anywhere in the console. For more details, see [Working with the console](https://docs.aws.amazon.com/waf/latest/developerguide/working-with-console.html).
# Using the CAPTCHA JavaScript API
This section provides instructions for using the CAPTCHA integration API.
The CAPTCHA JavaScript API allows you to configure the CAPTCHA puzzle and place it where you want in your client application. This API leverages the features of the intelligent threat JavaScript APIs to acquire and use AWS WAF tokens after an end user successfully completes a CAPTCHA puzzle.
Implement the JavaScript integration first in a test environment, then in production. For additional coding guidance, see the sections that follow.
**To use the CAPTCHA integration API**
1. **Install the API**
1. Sign in to the AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2).
1. In the navigation pane, choose **Application integration**. On the **Application integration** page, you can see tabbed options.
1. Select **CAPTCHA integration**.
1. Copy the listed JavaScript integration script tag for use in your integration.
1. In your application page code, in the `` section, insert the script tag that you copied. This inclusion makes the CAPTCHA puzzle available for configuration and use.
```
```
This `
```
**Example configuration settings**
The following example listing shows the `renderCaptcha` with non-default settings for the width and the title options.
```
AwsWafCaptcha.renderCaptcha(container, {
apiKey: "...API key goes here...",
onSuccess: captchaExampleSuccessFunction,
onError: captchaExampleErrorFunction,
dynamicWidth: true,
skipTitle: true
});
```
For full information about the configuration options, see [CAPTCHA JavaScript API specification](waf-js-captcha-api-specification.md).
# Handling a CAPTCHA response from AWS WAF
This section provides an example of handling a CAPTCHA response.
An AWS WAF rule with a CAPTCHA action terminates the evaluation of a matching web request if the request doesn't have a token with a valid CAPTCHA timestamp. If the request is a `GET` text/html call, the CAPTCHA action then serves the client an interstitial with a CAPTCHA puzzle. When you don't integrate the CAPTCHA JavaScript API, the interstitial runs the puzzle and, if the end user successfully solves it, automatically resubmits the request.
When you integrate the CAPTCHA JavaScript API and customize your CAPTCHA handling, you need to detect the terminating CAPTCHA response, serve your custom CAPTCHA, and then if the end user successfully solves the puzzle, resubmit the client's web request.
The following code example shows how to do this.
**Note**
The AWS WAF CAPTCHA action response has a status code of HTTP 405, which we use to recognize the CAPTCHA response in this code. If your protected endpoint uses an HTTP 405 status code to communicate any other type of response for the same call, this example code will render a CAPTCHA puzzle for those responses as well.
```
```
# Managing API keys for the JS CAPTCHA API
This section provides instructions for generating and deleting API keys.
To integrate AWS WAF CAPTCHA into a a client application with the JavaScript API, you need the JavaScript API integration tag and the encrypted API key for the client domain where you want to run your CAPTCHA puzzle.
The CAPTCHA application integration for JavaScript uses the encrypted API keys to verify that the client application domain has permission to use the AWS WAF CAPTCHA API. When you call the CAPTCHA API from your JavaScript client, you provide an API key with a domain list that includes a domain for the current client. You can list up to 5 domains in a single encrypted key.
**API key requirements**
The API key that you use in your CAPTCHA integration must contain a domain that applies to the client where you use the key.
+ If you specify a `window.awsWafCookieDomainList` in your client's intelligent threat integration, then at least one domain in your API key must be an exact match for one of the token domains in `window.awsWafCookieDomainList` or it must be the apex domain of one of those token domains.
For example, for the token domain `mySubdomain.myApex.com`, the API key `mySubdomain.myApex.com` is an exact match and the API key `myApex.com` is the apex domain. Either key matches the token domain.
For information about the setting the token domain list, see [Providing domains for use in the tokens](waf-js-challenge-api-set-token-domain.md).
+ Otherwise, the current domain must be contained in the API key. The current domain is the domain that you can see in the browser address bar.
The domains that you use must be ones that AWS WAF will accept, based on the protected host domain and the token domain list that's configured for the web ACL. For more information, see [AWS WAF protection pack (web ACL) token domain list configuration](waf-tokens-domains.md#waf-tokens-domain-lists).
**How to choose the Region for your API key**
AWS WAF can generate CAPTCHA API keys in any Region where AWS WAF is available.
As a general rule, you should use the same Region for your CAPTCHA API key as you use for your protection pack (web ACL). If you expect a global audience for a regional protection pack (web ACL), however, you can obtain a CAPTCHA JavaScript integration tag that's scoped to CloudFront and an API key that's scoped to CloudFront, and use them with a regional protection pack (web ACL). This approach allows clients to load a CAPTCHA puzzle from the Region that's closest to them, which reduces latency.
CAPTCHA API keys that are scoped to Regions other than CloudFront are not supported for use across multiple Regions. They can only be used in the Region they are scoped to.
**To generate an API key for your client domains**
To obtain the integration URL and generate and retrieve the API keys through the console.
1. Sign in to the AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2).
1. In the navigation pane, choose **Application integration**.
1. In the pane, **protection packs (web ACLs) that are enabled for application integration**, select the Region that you want to use for your API key. You can also select the Region in the **API keys** pane of the **CAPTCHA integration** tab.
1. Choose the tab **CAPTCHA integration**. This tab provides the CAPTCHA JavaScript integration tag, which you can use in your integration, and the API keys listing. Both are scoped to the selected Region.
1. In the **API keys** pane, choose **Generate key**. The key generation dialogue appears.
1. Enter the client domains that you want to include in the key. You can enter up to 5. When you're finished, choose **Generate key**. The interface returns to the CAPTCHA integration tab, where your new key is listed.
Once created, an API key is immutable. If you need to make changes to a key, generate a new key and use that instead.
1. (Optional) Copy the newly generated key for use in your integration.
You can also use the REST APIs or one of the language-specific AWS SDKs for this work. The REST API calls are [CreateAPIKey](https://docs.aws.amazon.com/waf/latest/APIReference/API_CreateAPIKey.html) and [ListAPIKeys](https://docs.aws.amazon.com/waf/latest/APIReference/API_ListAPIKeys.html).
**To delete an API key**
To delete an API key, you must use the REST API or one of the language specific AWS SDKs. The REST API call is [DeleteAPIKey](https://docs.aws.amazon.com/waf/latest/APIReference/API_DeleteAPIKey.html). You can't use the console to delete a key.
After you delete a key, it can take up to 24 hours for AWS WAF to disallow use of the key in all regions.