Learn how to create API keys and tokens to manage your Cloudflare account settings.

Overview

The Cloudflare API exposes the entire Cloudflare functionality via a programmatic interface. You can manage your account settings, configure products, and develop applications using the Cloudflare API.

Using the Cloudflare API requires either an API token or API key to authenticate the source of the API request. To learn more about the authentication process, review the Cloudflare API documentation.

An API key is unique to each Cloudflare user and used only for authentication. The API key does not authorize access to accounts or zones. 

API tokens allow you to authorize access to specific Cloudflare apps, accounts, and zones with limited permissions. Each Cloudflare user can have up to 50 API tokens associated with their Cloudflare account.

API tokens are associated with the user that created them. If your Cloudflare account is invalidated or your permissions change, you will lose access to your API token.

Generate API token

To generate an API token:

1. Log in to the Cloudflare dashboard.

2. Under the My Profile dropdown, click My Profile.

3. Click the API tokens tab.

4. Click the Create Token button. You will see the Create Token screen.

5. You have two configuration options to select from:

• Click Get Started in the Custom token section to manually set your desired token configuration. Then, proceed to Step 6.

• Select Start with a template to choose from a list of common configurations. Choose a template, then click Use template. Then, proceed to Step 6.

6. Select the following edit or read Permissions:

• Account or Zone Resources: API token will include or exclude your account(s) or the domains and subdomains associated with your account(s).

7. Select the following edit or read Resources:

• Account or Zone: API token will apply to your account(s) or the domains and subdomains associated with your account(s).

8. Click Continue to summary.

9. Review the API token details, then click Create Token to finish. You will see a confirmation message with your API token.

10. Click Copy to save your API token on your computer. This token contains your secret key, so be sure to save it in a secure location.

Roll API token

If your API token is compromised or lost, you can either create a new token or Roll your secret key into a new one. Rolling your secret key will authorize the same access and permissions as the previous key.

To roll your API token, click Roll in the API Tokens section of the Cloudflare dashboard.

Then, click Confirm to continue and you will see a new API token secret key.

View API Key

To retrieve your API key:

1. Log in to the Cloudflare dashboard.

2. Under the My Profile dropdown, click My Profile.

3. Click the API tokens tab.

4. In the API keys section, choose one of two options: Global API Key or Origin CA Key. Choose the API Key that you would like to view.

5. To change your API Key, click Change. You will need to complete a Captcha before the change is applied.

Main Causes for API Token Related Issues

• The token itself is not verified

You can ensure the token has been verified by running the following curl and confirm the response returns "status": "active".

#cURL (example)
curl -X GET "https://api.cloudflare.com/client/v4/user/tokens/verify" \
-H "Authorization: Bearer " \
-H "Content-Type:application/json"

#Response (example)
{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "f267e341f3dd4697bd3b9f71dd96247f",
    "status": "active",
    "not_before": "2018-07-01T05:20:00Z",
    "expires_on": "2020-01-01T00:00:00Z"
  }

• The token has incorrect permissions

Send us a screenshot of the permissions you have set up to verify if the permission has been set correctly or not. 

• Incorrect Syntax

On occasion, customers will attempt to use an API Token with an API Key syntax. Ensure you are using the Bearer option, rather than the Email and API key pair.

curl -X GET "https://api.cloudflare.com/client/v4/user/tokens?page=1&per_page=20&direction=desc" \
-H "Authorization: Bearer 8M7wS6hCpXVc-DoRnPPY_UCWPgy8aea4Wy6kCe5T"

• Incorrect User Permissions when attempting to create Token

A customer cannot create a token for themselves that exceeds the permission granted to them on their Account. For example, if a customer has been granted an Admin (Read only) role, they would need their Super Administror to update their role so that they could create a token for themselves.

Related resources

• Cloudflare API documentation