Some applications or reseller host providers might find it handy to know about CloudFlare's IPs. This page is intended to be the source of CloudFlare's current IP ranges.
IPv4
204.93.240.0/24
204.93.177.0/24
199.27.128.0/21
173.245.48.0/20
103.21.244.0/22
103.22.200.0/22
103.31.4.0/22
141.101.64.0/18
108.162.192.0/18
190.93.240.0/20
188.114.96.0/20
197.234.240.0/22
198.41.128.0/17
IPv6
2400:cb00::/32
2606:4700::/32
2803:f800::/32
2405:b500::/32
2405:8100::/32
Copyright © 2012 CloudFlare, Inc. All rights reserved.
1 - Overview
This document explains in detail the semantics of the function calls you can make using the Hosting Provider API service. This service is limited to access by web hosting providers who have agreed to the required license terms.
In this document, you will learn:
- How the CloudFlare Hosting Provider API syntax works and how operations are performed.
- How to register your users with the CloudFlare system.
- How to register your users' domains to be hosted by CloudFlare system.
- How to resell CloudFlare products for your users' domains.
- How to interpret the results you receive back from the CloudFlare systems.
- What error codes you may encounter mean and how to resolve them.
- There is a separate API document to integrate basic statistics and CloudFlare settings. This document is known as the Client Interface API. The latest version is maintained here.
This document is subject to change. The latest version of this document is always maintained at:
https://www.cloudflare.com/docs/host-api.html
The Client Interface API document is maintained at:
https://www.cloudflare.com/docs/client-api.html
If you have comments, find errors, or have questions, please contact .
1.1 - Interaction with the CloudFlare System
Interaction with the CloudFlare system is accomplished with POST requests through the secure HTTP protocol (HTTPS). This protocol was chosen for its simplicity, network administrators' familiarity with it, its ability to pass through many corporate firewalls without requiring their modification, the protocol's extensive documentation, and the wide availability of access tools written in many languages.
Some links concerning establishing and performing POST requests over secure HTTP sessions are provided below:
- Java (HttpsURLConnection)
- PHP (fsockopen)
- PHP (curl)
- Python (urllib)
- Windows (WinInet | HttpWebRequest Class)
1.2 - General Issues Checklist
There are some general issues that you should keep in mind when designing an application for interacting with this API. You may want to refer to this checklist as you are constructing the application. Neglecting to follow these general guidelines is the usual source of difficulty for application designers.
- All requests should be established via a secure SSL connection through the HTTPS protocol.
- All operation requests are initiated via a POST request from the client to the CloudFlare system.
- The order in which you pass the POST parameters does not matter.
- All responses are returned as JSON.
- The precise order of the fields in the JSON responses, as described in the examples in this document, may change and should not be relied upon.
- Samples POSTS provided on this page use the common unix curl utility. The -d options sets a POST parameter.
- For added security, your access to the API may be restricted to the set of IPs you listed when you created your account. You may change these IPs if your setup changes.
1.3 - Getting Setup Quickly
At a minimum, host providers should implement the user_create (Section 3.2.1) and zone_set (Section 3.2.2) operations. Hosting providers also need to implement a way to update their DNS records to point any subdomains setup with CloudFlare to the appropriate forward_tos address.
2 - Client Operations
Every operation request from a client application to the CloudFlare system is accomplished as a POST request through the HTTPS protocol. For more information on passing form data via POST requests, see RFC 1867.
All POSTs should be directed at the host provider gateway interface, located at:
https://api.cloudflare.com/host-gw.htmlWe have included simple code samples, written in common languages, to assist you in developing your POST functionality. Please click the link below that corresponds to your development platform:
All operations return a JSON response to indicate whether the POST was completed successfully. In the REQUEST portion of the JSON response, the "act" parameter is echoed back in order to help you keep track of which operation obtained the returned result.
Unsuccessful requests will return an error code as well as an error message. The error message is suitably formatted to be displayed to an end user of the application interfacing with the API. Here is an example:
-
-request: {
- act: "user_create"
- result: "error",
- msg: "Please provide a CloudFlare e-mail address.",
- err_code: 103
The err_code is always a 3 digit numbers. The msg will contain
an explanation of the error that was encountered. The msg parameter will be suitably formatted to be displayed to an end user of the application interfacing with the API.
For an explanation of the specific error codes, see Section 4 of this document.
Successful requests may also include a msg. If present, the message will be suitably formatted to be displayed to an end user. If no msg is present the parameter will be set to null. In all cases, the msg parameter will be an ASCII string not longer than 1,000 characters.
3.1 - Basic Parameters
Every POST request must include at the following basic parameter(s):
- "host_key"
Host Providers who have been granted access to the API are issued a
host_keykey. These keys are 32 characters in length and may be locked to a particular set of IP addresses. - "act"
To define which request is being made, the client should POST an "
act" parameter. The "act" specifies which action you'd like to perform, such as user account creation, user account lookups, setting up a zones CNAMEs, etc. Depending on the particular request, additional parameters may also be required. Specific actions are described in Section 3.2 below.
3.2 - Specific Host Provider Operations
Interaction with the CloudFlare system is accomplished
through the use of various operations. These operations are commenced
with predefined "act" or action parameters. These actions are specified via the act parameter as
part of the POST request. The currently supported actions are listed in the following subsections,
along with descriptions of each action's purpose.
At a minimum, hosting providers should support the user_create and zone_set actions, as described in Section 3.2.1 and 3.2.2 respectively. Additional actions may be supported in order to make your application more full featured for your users.
3.2.1 - "user_create" - Create a CloudFlare account mapped to your user (required)
This act parameter is used to create a new CloudFlare account on behalf of one of your users.
If you know that your User already has an existing account with CloudFlare, use the "user_auth" operation,
described in Section 3.2.2, instead. For your convenience, CloudFlare will
automatically perform a "user_auth" operation (Section 3.2.2) if the CloudFlare account already exists.
| Input: | Requires the basic parameters described in Section 3.1 of this document. In addition, you must pass the following parameters via the POST request.
Here is an example POST to the user_create action: curl https://api.cloudflare.com/host-gw.html \ -d 'act=user_create' \ -d 'host_key=8afbe6dea02407989af4dd4c97bb6e25' \ -d 'cloudflare_email=[email protected]' \ -d 'cloudflare_pass=newpassword' \ -d 'unique_id=someuniqueid' |
| Output: | If the information to create a new CloudFlare user account is valid and no errors occur,
the "user_create" action will echo the request and return a Important: If no Here is a successful JSON response to the POST described in the INPUT section above:
{
The |
3.2.2 - "zone_set" - Setup a User's zone for CNAME hosting (required)
This act parameter is used to set up CNAME record hosting for a User's zone.
The user_key is required. If you do not have the user_key on hand, perform a "user_lookup" (see Section 3.2.3).
| Input: | Requires the basic parameters described in Section 3.1 of this document. In addition, you must pass the following parameters via the POST request.
Here is an example POST to the zone_set action: curl https://api.cloudflare.com/host-gw.html \ -d 'act=zone_set' \ -d 'host_key=8afbe6dea02407989af4dd4c97bb6e25' \ -d 'user_key=57bd6ab7536daa87cab966ad723f014a' \ -d 'zone_name=someexample.com' \ -d 'resolve_to=cloudflare-resolve-to.someexample.com' \ -d 'subdomains=www,blog,wordpress:cloudflare-rs2.someexample.com' If run, the intent of the above action would be to configure the CloudFlare system such that it would accept traffic to www.someexample.com and blog.someexample.com. After having been routed through the CloudFlare network, if the traffic is clean and cannot be handled by the CloudFlare cache, it will be relayed to cloudflare-resolve-to.someexample.com. Traffic to another subdomain (e.g., forum.someexample.com) would not be setup to run through CloudFlare. Note: The zone_set action replaces any previous setup for the particular Note: The wordpress subdomain above is configured to be relayed to the CNAME cloudflare-rs2.someexample.com, rather than the default cloudflare-resolve-to.someexample.com. |
| Output: | If the information to setup a zone is valid and no errors occur,
the "zone_set" action will return the A successful response to the POST from the INPUT section above:
{
Important: To complete setup for your user, you should automatically update your user's DNS settings to resolve the subdomains specified in zone_set or zone_lookup to the corresponding ;; ANSWER SECTION: www.someexample.com. 900 IN CNAME www.someexample.com.cdn.cloudflare.net. |
3.2.3 - "user_lookup" - Lookup a user's CloudFlare account information (optional)
This act parameter is used to lookup information about a User's existing CloudFlare account.
This action is typically used to check if the account exists or to retrieve a user_key. You do not need to support this function if you plan to store the user_key on your system.
| Input: | Requires the basic parameters described in Section 3.1 of this document. In addition, you must pass the following parameters via the POST request.
Here is an example POST to the user_lookup action: curl https://api.cloudflare.com/host-gw.html \ -d 'act=user_lookup' \ -d 'host_key=8afbe6dea02407989af4dd4c97bb6e25' \ -d 'unique_id=someuniqueid' |
| Output: | If the information to lookup the status of a CloudFlare account is valid and no errors occur,
the "user_lookup" action will return the A successful response to the POST from the INPUT section above:
{
The |
3.2.4 - "user_auth" - Authorize access to a user's existing CloudFlare account (optional)
This act parameter is used to gain access to a User's existing CloudFlare account.
This action is automatically called by "user_create" (Section 3.2.1) if
the CloudFlare account already exists. In most cases, when setting up an account, you should use user_create unless you know a user already has a CloudFlare account.
| Input: | Requires the basic parameters described in Section 3.1 of this document. In addition, you must pass the following parameters via the POST request.
Here is an example POST to the user_auth action: curl https://api.cloudflare.com/host-gw.html \ -d 'act=user_auth' \ -d 'host_key=8afbe6dea02407989af4dd4c97bb6e25' \ -d 'cloudflare_email=[email protected]' \ -d 'cloudflare_pass=newpassword' \ -d 'unique_id=someuniqueid' |
| Output: | If the information to auth a new CloudFlare user account is valid and no errors occur,
the "user_auth" action will return a A successful response to the POST from the INPUT section above:
{
|
3.2.5 - "zone_lookup" - lookup a specific user's zone (optional)
This act parameter is used to lookup information about a User's zone in the CloudFlare system.
This action is typically used to check if the zone exists (zone_exits is true) or if you register as the host (zone_hosted is true).
| Input: | Requires the basic parameters described in Section 3.1 of this document. In addition, you must pass the following parameters via the POST request.
Here is an example POST to the zone_lookup action: curl https://api.cloudflare.com/host-gw.html \ -d 'act=zone_lookup' \ -d 'host_key=8afbe6dea02407989af4dd4c97bb6e25' \ -d 'user_key=57bd6ab7536daa87cab966ad723f014a' \ -d 'zone_name=someexample.com' |
| Output: | If the information to lookup the status of a CloudFlare account is valid and no errors occur,
the "zone_lookup" action will return the A successful response to the POST from the INPUT section above:
{
The following describes specific statuses of certain elements on the response.
|
3.2.6 - "zone_delete" - delete a specific zone on behalf of a user (optional)
This act parameter is used to delete a User's previously "zone_set" zone in the CloudFlare system.
CloudFlare will stop honoring DNS requests for deleted zones after a short period of time. Be sure to unset all
CloudFlare forwarded CNAMEs prior to or immediately after a "zone_delete".
| Input: | Requires the basic parameters described in Section 3.1 of this document. In addition, you must pass the following parameters via the POST request.
Here is an example POST to the zone_delete action: curl https://api.cloudflare.com/host-gw.html \ -d 'act=zone_delete' \ -d 'host_key=8afbe6dea02407989af4dd4c97bb6e25' \ -d 'user_key=57bd6ab7536daa87cab966ad723f014a' \ -d 'zone_name=someexample.com' |
| Output: | If the information to lookup the status of a CloudFlare account is valid and no errors occur,
the "zone_delete" action will return a success A successful response to the POST from the INPUT section above:
{
|
3.2.7 - "host_child_new" - Create a new child host provider (required)
This act parameter is used to create a new CloudFlare child host provider on behalf of one of your host provider accounts.
| Input: | Requires the basic parameters described in Section 3.1 of this document. In addition, you must pass the following parameters via the POST request.
Here is an example POST to the host_child_new action: curl https://api.cloudflare.com/host-gw.html \ -d 'act=host_child_new' \ -d 'host_key=910c55ffe900a42378785ee666393ac5' \ -d 'host_name=XYZ Hosting Reseller' \ -d 'pub_name=Your Host Provider' \ -d 'prefix=core' \ -d 'website=http://www.xyz.com' \ -d 'email=[email protected]' |
| Output: | If the information to create a new CloudFlare child host provider account is valid and no errors occur,
the "host_child_new" action will echo the request and return the Here is a successful JSON response to the POST described in the INPUT section above:
{
If there is no |
3.2.8 - "host_key_regen" - Regenerate your host key(optional)
This act parameter is used to change a host key for a CloudFlare host provider account.
| Input: | Requires the basic parameters described in Section 3.1 of this document. In addition, you must pass the following parameters via the POST request. Here is an example POST to the host_key_regen action: curl https://api.cloudflare.com/host-gw.html \ -d 'act=host_key_regen' \ -d 'host_key=aecogk1c19f0e6058afc8e0c067abcfb' |
| Output: | If the information to regenerate a new host key for the CloudFlare host provider account is valid and no errors occur,
the "host_key_regen" action will echo the request and return the newly generated Here is a successful JSON response to the POST described in the INPUT section above:
{
If there is no |
3.2.9 - "host_child_stop" - Stop a child host provider account (required)
This act parameter is used to stop a CloudFlare child host provider account.
| Input: | Requires the basic parameters described in Section 3.1 of this document. In addition, you must pass the following parameters via the POST request.
Here is an example POST to the host_child_stop action: curl https://api.cloudflare.com/host-gw.html \ -d 'act=host_child_stop' \ -d 'host_key=910c55ffe900a42378785ee666393ac5' \ -d 'child_id=112' |
| Output: | If the information to stop a child host provider account is valid and no errors occur,
the "host_child_stop" action will echo the request and return the Here is a successful JSON response to the POST described in the INPUT section above:
{
If there is no |
3.2.10 - "zone_list" - List the domains currently active on CloudFlare for the given host (optional)
This act parameter is used to request the complete list of domains which CloudFlare believes is active for your host.
The limit, offset, zone_name, and sub_id parameters are all optional. They default to 100, 0, NULL and NULL respectively.
The sub_id applies to CloudFlare Resellers only. The zone_status parameter is also optional. Value is in V,D,ALL, where V shows active zones only, D deleted, and ALL all.
| Input: | Requires the basic parameters described in Section 3.1 of this document. Here is an example POST to the zone_list action: curl https://api.cloudflare.com/host-gw.html \ -d 'act=zone_list' \ -d 'host_key=8afbe6dea02407989af4dd4c97bb6e25' \ -d 'limit=10' \ -d 'offset=0'\ -d 'zone_name=example.com' \ -d 'sub_id=1023' \ -d 'zone_status=ALL' |
| Output: | If the information to lookup the status of a CloudFlare account is valid and no errors occur, the "zone_list" action will return a list of zones. A successful response to the POST from the INPUT section above: {
Zone status codes are
Note: subscriptions are per zone. If a zone does not have a subscription, the subscription information will be null. |
Note: subscriptions are per zone. If a zone does not have a subscription, the subscription information will be null.
4 - Error Feedback and Codes
You may encounter error codes when running a transaction. These codes are all formatted as a 3-digit number.
In addition to the error code, a msg parameter will be included for every error. This msg parameter is formatted appropriately to be displayed to the end user.
4.1 - Responding to Error Conditions
In section 4.2 of this document, the specific error codes are outlined. Accompanying each error code is a description of the error. Applications designed to interface with the CloudFlare API should be aware of these errors and tested to ensure they can respond appropriately. The error messages can safely be relayed to the end user.
4.2 - Error Codes
Error code 100: No or invalid host_key.
Error code 101: No or invalid act.
Error code 103: Please provide a CloudFlare e-mail address.
Error code 104: Invalid unique_id. Allowed character set is '-_a-z0-9#@+.,'.
Error code 105: Invalid unique_id. Max size exceeed.
Error code 106: Invalid clobber_unique_id. Must be 0 or 1.
Error code 107: That action requires either 'cloudflare_email' or 'unique_id' to be defined.
Error code 108: Please provide a CloudFlare password.
Error code 109: CloudFlare password is too obvious.
Error code 110: Your CloudFlare password must be at least 6 characters.
Error code 111: Please provide a CloudFlare username.
Error code 112: Please provide a CloudFlare username of at least 3 characters.
Error code 113: CloudFlare usernames must consist of letters and numbers. Delineation using . - or _ characters is allowed. You entered "[$cloudflare_username]".
Error code 114: That CloudFlare username is too close to a disallowed name. You entered "[$cloudflare_username]".
Error code 115: No user_key.
Error code 116: Invalid user_key.
Error code 117: The unique_id '[$unique_id]' has already been assigned to a different user.
Error code 118: CloudFlare account "[$cloudflare_email]" already exists.
Error code 119: The CloudFlare email address "[$cloudflare_email]" has already been registered, but has not been confirmed. Please double check your mail box for the confirmation link.
Error code 120: The CloudFlare email address "[$cloudflare_email]" is already in use. If you have forgotten your CloudFlare password, you may reset it.
Error code 121: The CloudFlare invitation code "[$signup_code]" is not currently valid or has expired.
Error code 122: The CloudFlare username '[$cloudflare_username]' has been taken. Please choose another.
Error code 123: CloudFlare account [$cloudflare_email] does not exist.
Error code 124: Password failed for CloudFlare account "[$cloudflare_email]". Try again or reset your password.
Error code 125: User with user_key [$user_key] does not exist.
Error code 126: Please correct your CloudFlare e-mail address. You entered "[$cloudflare_email]".
Error code 200: No zone_name.
Error code 201: Invalid zone_name.
Error code 202: No resolve_to.
Error code 203: Invalid resolve_to.
Error code 204: No subdomains.
Error code 205: Invalid host value '[$subdomain]' found in subdomains. Not all characters are in allowed set.
Error code 206: Invalid host value '[$subdomain]' found in subdomains. Must be less than 120 characters.
Error code 207: CloudFlare is already hosting [$zone_name] for you.
Error code 208: CloudFlare is already hosting "[$zone_name]" under a different account. If you are the new, rightful owner, please contact CloudFlare and reference this message (#208).
Error code 209: CloudFlare is already hosting "[$zone_name]" under a different account. If you are the new, rightful owner, please contact CloudFlare and reference this message (#209).
Error code 210: CloudFlare could not delete [$zone_name]. It was not found in your account.
Error code 211: CloudFlare can not delete [$zone_name]. It has already been banned or removed from your CloudFlare account.
Error code 212: CloudFlare can not delete [$zone_name] from this interface. [$host_provider] is not the authoritative parter with CloudFlare for your domain.
Error code 213: CloudFlare can not delete [$zone_name]. It has already been removed from your CloudFlare account.
Error code 214: CloudFlare is the authorative DNS provider for [$zone_name]. You must login to CloudFlare to deactivate or delete your domain there.
Error code 215: CloudFlare is currently limiting new site signups. Your site [$zone_name] is in the queue. A notification will be sent when your site clears the queue.
Error code 216: Your [$zone_name]'s DNS is hosted by CloudFlare. If you'd like to switch to "[$host_provider]", you must first deactivate and then delete [$zone_name] within CloudFlare. These options are available in the Settings menu.
Error code 217: CloudFlare is not servicing "[$zone_name]" through this [$host_provider]. If you are the rightful owner, you can swap over by deleting any previous CloudFlare domain sign-up and restarting this process. You may also contact CloudFlare and reference this message (#217).
Error code 218: CloudFlare could not detect "[$zone_name]" as a registered domain.
Error code 600: No POST data received.
Error code 601: Connection to CloudFlare DB systems could not be established. Try again in a few minutes. If this problem persists, please contact CloudFlare and reference this message (#601).
Error code 700: Invalid host account [$host_key].
Error code 701: An unknown CloudFlare error has occurred during zone creation and has been logged. We apologize for the inconvenience and we will fix the problem promptly.
Error code 702: An unknown CloudFlare error has occurred during zone authorization and has been logged. We apologize for the inconvenience and we will fix the problem promptly.
Error code 703: An unknown CloudFlare error has occurred during zone deletion and has been logged. We apologize for the inconvenience and we will fix the problem promptly.
Error code 311: Invalid User.
Error code 312: Invalid Sub Label.
Error code 313: Sub label will not accept new subscriptions.
Error code 314: Already subscribed and is active.
Error code 315: Already subscribed and the sub cannot be re-activated.
Error code 317: Invalid Zone.
Error code 321: Zone is not active.
Error code 322: Zone is already subscribed to a different sub.
Error code 340: Other Error (Subscribe).
Error code 350: Zone is not active on CloudFlare.
Error code 331: Invalid Subscription Id.
Error code 332: Sub is already canceled.
Error code 333: Other Error (Unsubscribe)
Error code 334: [$zone_name] currently has an active reseller sub. Cancel this subscription before deleting the zone.
4.3 - Error Message Variable Expansions
Certain error messages contain variables, denoted like [$zone_name] or $[host_key]. The different variables are outlined below.
- [$cloudflare_email]: Your client's CloudFlare account e-mail: "[email protected]"
- [$host_provider]: Either, 1) the common public name that CloudFlare has on file for your company: "Example Hosting"; OR 2) if you are setup with a reseller's key, then the anonymous string: "this provider"
- [$host_key]: Your host key: "c15cedb807ceb3d71a3bcc9c8640538c"
- [$zone_name]: Expanded to your base domain: "example.com"
