Admiral Online participated in the CloudFlare community. CloudFlare DNS protects and accelerates any website online. Once a website is a part of the CloudFlare community, its web traffic is routed through the CloudFlare intelligent global network. It automatically optimizes the delivery of web pages so visitors get the fastest page load times and best performance. It also blocks threats and limit abusive bots and crawlers from wasting bandwidth and server resources. The result: CloudFlare-powered websites see a significant improvement in performance and a decrease in spam and other attacks. Below is the copyrighted excert of the hosting API which can be used by Admiral Online resellers after they have executed license agreements with CloudFlare.

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.

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:

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.

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.

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.

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.html

We 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.

Host Providers who have been granted access to the API are
issued a host_key key. 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.

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.

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.

"cloudflare_email"

The User's e-mail address for the new CloudFlare account.

"cloudflare_pass"

The User's password for the new CloudFlare account. CloudFlare will never store this password in clear text.

"cloudflare_username" (optional)

The User's username for the new CloudFlare account. CloudFlare will auto-generate one if it is not specified.

"unique_id" (optional)

Set a unique string identifying the User. This identifier will serve as an alias to the user's CloudFlare account.
Typically you would set this value to the unique ID in your system (e.g., the internal customer number or username stored in your own system). This parameter can be used to retrieve a user_key when it is required. The unique_id must be an ASCII string with a maximum length of 100 characters.

"clobber_unique_id" (optional)

Any operations that can set a unique_id can be set to automatically "clobber" or unset a previously assigned unique_id.

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 user_key. A user_key is a string of ASCII characters with a maximum length of 32 characters.

Important: If no unique_id is specified,
the user_key should be stored in your system. Certain actions to modify the new user's setup, such as user_lookup or
zone_set, will require the user_key. If you have specified a unique_id (e.g., the internal customer number or username stored in your own system) then you can always use that to retrieve the user_key. You should be able to lookup from your own system the user_key, the unique_id, or both.

Here is a successful JSON response to the POST described in the INPUT section above:

The zone you'd like to run CNAMES through CloudFlare for, e.g. "example.com".

"resolve_to"

The CNAME that CloudFlare should ultimately resolve web connections to after they have been filtered, e.g. "resolve-to-cloudflare.example.com". This record should ultimately resolve to the one or more IP addresses of the hosts for the particular website for all the specified subdomains. Note: it CANNOT be the naked zone name, in this case example.com

"subdomains"

A comma-separated string of subdomain(s) that CloudFlare should host, e.g. "www,blog,forums" or "www.example.com,blog.example.com,forums.example.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 zone_name. If are adding an additional subdomain to an account that already has some subdomains setup, you should specify all the subdomains not only the new subdomains.

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 zone_name (string),
resolving_to (string), hosted_cnames (map), and forward_tos (map) as confirmation. The forward_tos will be in the format of the fully qualified domain plus cdn.cloudflare.net (e.g., www.example.com.cdn.cloudflare.net or blog.example.com.cdn.cloudflare.net) .

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 forward_tos. Until you complete this step, traffic will not be routed through the CloudFlare system. For your DNS settings, we recommend a TTL for the record of not less than 900 seconds. You should setup your user's DNS records for each subdomain to mirror the following results:

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.

"cloudflare_email" or "unique_id"

Lookup a user's account information or status by either cloudflare_email or unique_id.

If the information to lookup the status of a CloudFlare account is valid and no errors occur,
the "user_lookup" action will return the user_key (string), user_exists (boolean),
user_authed (boolean), cloudflare_email (string), unique_id (string), and hosted_zones (array).

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.

"cloudflare_email"

The User's e-mail address for the new CloudFlare account.

"cloudflare_pass"

The User's password for the new CloudFlare account. CloudFlare will never store this password in clear text.

"unique_id" (optional)

Set a unique string identifying the User. This identifier will serve as an alias to the user's CloudFlare account.
Typically you would set this value to the unique ID in your system. This parameter can be used as an alias for other actions (e.g., it can substitute for the cloudflare_email and cloudflare_password if you choose not to store those fields in your system).

"clobber_unique_id" (optional)

Any operations that can set a unique_id can be set to automatically "clobber" or unset a previously assigned unique_id.

If the information to auth a new CloudFlare user account is valid and no errors occur,
the "user_auth" action will return a user_key. If no unique_id is specified,
the user_key should be stored in your system. Certain actions, such as user_lookup or
zone_set require the user_key.

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.

If the information to lookup the status of a CloudFlare account is valid and no errors occur,
the "zone_lookup" action will return the zone_name (string), zones_exists (boolean),
zone_hosted (boolean), hosted_cnames (map), and forward_tos (map).

A successful response to the POST from the INPUT section above:

{

-

request: {

act: "zone_lookup"

}

-

response: {

zone_name: "someexample.com"

zone_exists: true

zone_hosted: true

-

hosted_cnames: {

someexample.com: "cloudflare-resolve-to.someexample.com"

blog.someexample.com: "cloudflare-resolve-to.someexample.com"

www.someexample.com: "cloudflare-resolve-to.someexample.com"

}

-

forward_tos: {

someexample.com: "someexample.com.cdn.cloudflare.net"

blog.someexample.com: "blog.someexample.com.cdn.cloudflare.net"

www.someexample.com: "www.someexample.com.cdn.cloudflare.net"

}

ssl_status: "ready"

ssl_meta_tag: ""

sub_label: AWESOMEHOST_PLAN_PLUS

sub_status: V

}

result: "success"

msg: null

}

The following describes specific statuses of certain elements on the response.

"ssl_status"

This status will be set to "ready" when the zone's SSL certificate has been activated on CloudFlare.

"ssl_meta_tag"

The SSL META tag needs to be inserted in the HEAD of the index page of the zone in order for the SSL certificate to be issued.

"sub_label"

This subscription label will be set to a reseller specific value used to identify the zone's subscription.

"sub_status"

The subscription status value will be "V" for active and "D" for deleted.

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.

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 host_id and the api_key. The host_id and the api_key are correspond to the newly created child host, and the api_key(host_key) is a string of ASCII characters with a maximum length of 32 characters.

Here is a successful JSON response to the POST described in the INPUT section above:

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 host_key. Thehost_key is a string of ASCII characters with a maximum length of 32 characters.

Here is a successful JSON response to the POST described in the INPUT section above:

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 host_id of the child host provider account that was stopped.

Here is a successful JSON response to the POST described in the INPUT section above:

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.

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.

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.

[$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"