Cloudflare Reseller Provider API Version 1.0.0-Beta

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 Reseller 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:

This document is subject to change. The latest version of this document is always maintained at:

https://www.cloudflare.com/docs/reseller-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:

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.

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


3.1 - Basic Parameters

Every POST request must include at the following basic parameter(s):

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.

3.2.1 - "reseller_sub_new" - subscribe a domain to a premium plan (optional)

This act parameter is used to request that a domain be subscribed to one of Cloudflare's paid products. You will be invoiced monthly.

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.

  • "zone_name"

    The zone you'd like to subscribe, e.g. "example.com".

  • "plan_tag"

    The plan tag you wish to subscribe the zone too, e.g. "CF_RESELLER_PRO".

Here is an example POST to the reseller_sub_new action:

curl https://api.cloudflare.com/host-gw.html \
    -d 'act=reseller_sub_new' \
    -d 'host_key=8afbe6dea02407989af4dd4c97bb6e25' \
    -d 'user_key=57bd6ab7536daa87cab966ad723f014a' \
    -d 'zone_name=someexample.com' \
    -d 'plan_tag=CF_RESELLER_PRO' \
  

Output:

If the information to lookup the status of a Cloudflare account is valid and no errors occur, the "reseller_sub_new" action will return a success zone_name (string), sub_cost (numeric), sub_id (int).

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

  {
      request: {
          act: "reseller_sub_new"
          zone_name: "someexample.com"
          plan_tag: "CF_RESELLER_PRO"
      },
      response: {
          sub_cost: 19.95,
          sub_id: 17
      },
      result: "success",
      msg: null
  }
  

3.2.2 - "reseller_sub_cancel" - stop a subscription of a domain to a premium plan (optional)

This act parameter is used to request that a domain be removed from one of Cloudflare's paid products.

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.

  • "zone_name"

    The zone you'd like to subscribe, e.g. "example.com".

  • "plan_tag"

    The plan tag you wish to subscribe the zone too, e.g. "CF_RESELLER_PRO".

  • "sub_id"

    The ID of the subscription you wish to cancel, e.g. "17".

Here is an example POST to the reseller_sub_cancel action:

curl https://api.cloudflare.com/host-gw.html \
    -d 'act=reseller_sub_cancel' \
    -d 'host_key=8afbe6dea02407989af4dd4c97bb6e25' \
    -d 'user_key=57bd6ab7536daa87cab966ad723f014a' \
    -d 'zone_name=someexample.com' \
    -d 'plan_tag=CF_RESELLER_PRO' \
    -d 'sub_id=17' \
  

Output:

If the information to lookup the status of a Cloudflare account is valid and no errors occur, the "reseller_sub_cancel" action will return a success sub_id (int).

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

  {
      request: {
          act: "reseller_sub_cancel",
          zone_name: "someexample.com",
          plan_tag: "CF_RESELLER_PRO"
      },
      response: {
          sub_id: 17
      },
      result: "success",
      msg: null
  }
  

3.2.3 - "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 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:

  {
      request: {
          act: "zone_list"
      },
      response: [{
          sub_id: 17
          zone_id: 1
          sub_activated_on: "2011-11-23 17:58:56.791516-05"
          sub_status: "V"
          sub_expired_on: undef
          sub_label: "CF_RESELLER_PRO"
          zone_name: example.com
          user_email: [email protected]
          zone_status: 'V'
      }],
      result: "success",
      msg: null
  }
  

Zone status codes are

  • V: Active
  • D: Deleted
Subscription status codes are
  • V: Active
  • D: Deleted

Note: subscriptions are per zone. If a zone does not have a subscription, the subscription information will be null.

3.2.4 - "reseller_plan_list" - List the reseller plan tags for the given host (optional)

This act parameter is used to request the list of reseller plan tags which Cloudflare has for your host.

Input:

Requires the basic parameters described in Section 3.1 of this document.

Here is an example POST to the reseller_plan_list action:

curl https://api.cloudflare.com/host-gw.html \
    -d 'act=reseller_plan_list' \
    -d 'host_key=8afbe6dea02407989af4dd4c97bb6e25'
  

Output:

If the information to lookup the status of a Cloudflare account is valid and no errors occur, the "reseller_plan_list" action will return a list of subs.

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

  {
      request: {
          act: "reseller_plan_list"
      },
      response: {
          objs: [{
              sub_label: "HOST123-CLDF-PLUS-M"
              product_price: "5.00"
              sbase_name: "Cloudflare Plan Plus"
              sbase_landing: null
              ,
              {
              sub_label: "HOST123-CLDF-PREMIUM-M"
              product_price: "10.00"
              sbase_name: "Cloudflare Plan Premium"
              sbase_landing: null
          }]
      },
      result: "success",
      msg: null
  }
  

3.2.5 - "reseller_sub_list" - List the subscriptions for the given host

This act parameter is used to request the list of subscriptions for your host.

Input:

Requires the basic parameters described in Section 3.1 of this document.

Here is an example POST to the reseller_sub_list action:

curl https://api.cloudflare.com/host-gw.html \
    -d 'act=reseller_sub_list' \
    -d 'host_key=8afbe6dea02407989af4dd4c97bb6e25'
  

Output:

If the Cloudflare host account is valid and no errors occur, the "reseller_sub_list" action will return a list of host reseller subscriptions.

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

  {
      request: {
          act: "reseller_sub_list"
      },
      response: {
          objs: [{
              zone_name: "example1.com"
              sub_id: "1"
              sub_status: "V"
              sub_name: "Cloudflare Plan Plus"
              sub_price: "5.00"
              sub_priced_on: "2012-07-18 18:35:54.050883-05"
              sub_canceled_on: null
              sub_expires_on: null
              sub_expired_on: null
              sub_renewed_on: 2013-03-18 17:35:54.051223-05
              sub_activated_on: "2012-07-18 18:35:54.050883-05"
              edate: "2012-07-18 18:46:29.232158-05"
              cdate: "2012-07-18 18:35:54.050883-05"
              },
              {
              zone_name: "example2.com"
              sub_id: "2"
              sub_status: "CNL"
              sub_name: "Cloudflare Plan Plus"
              sub_price: "5.00"
              sub_priced_on: "2012-07-30 13:58:36.186028-05"
              sub_canceled_on: "2013-03-02 03:21:09.966943-05"
              sub_expires_on: "2013-03-02 03:21:09.966943-05"
              sub_expired_on: "2013-03-02 03:21:09.966943-05"
              sub_renewed_on: "2012-02-02 17:09:36.710008-05"
              sub_activated_on: "2012-07-30 17:09:36.710008-05"
              edate: "2013-03-02 03:21:09.966943-05"
              cdate: "2012-07-30 13:58:36.186028-05"
          }]
      },
      result: "success",
      msg: null
  }
  


Subscription status codes (denoted by sub_status) are

  • V: Active
  • CNL: Canceled



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.