Cloudflare App Integration API (BETA)
Version 0.1.0-Beta Copyright � 2011 Cloudflare, Inc.
All rights reserved.

1 - General Operations

Every operation request from 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 single common service provider gateway interface per application, located on the application provider's servers.

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 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 valid e-mail address.",
    err_code: 103
  }
  

The err_code is always a 3 digit number. 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.

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.

2.1 - Basic Parameters

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

"api_key" : A token unique to Cloudflare provided with every request to authenticate Cloudflare to the application provider.

"act" : The "act" specifies which action Cloudflare would like to perform. Depending on the particular request, additional parameters may also be required. Specific actions are described in Section 2.2 below.

2.2 - Specific Parameters for Operations

2.2.1 - "user_create" - Create an account on your service.

  INPUT:
  user_email    -- Email address of the activating user.                                                [REQUIRED]
  user_zone     -- Zone where the service is being activated on.                                        [REQUIRED]
  user_tos      -- User has accepted the TOS for the service. Boolean.                                  [REQUIRED]
  user_tokens   -- A json encoded map of token names to token values. Specific to each service.         [OPTIONAL]

  RESPONSE:
  {
  -request: {
      act: "user_create"
    },
    -response: {
      user_email:    "[email protected]",
      user_zone:     "example.com",
      service_id:    "MY_CF_APP_IP",
      service_url:   "www.myservice.com/login?uid=1234"
    },
    result: "success",
    msg: "Your new FOOBAR account was created, you can login at www.foobar.com with the email address ([email protected]) to see your results."
  }
  

2.2.1 - "user_deactivate" - Deactivate an acount on your service. (Optional)

  INPUT:
  user_email    -- Email address of the deactivating user.                                             [REQUIRED]
  user_zone     -- Zone where the service is being deactivated on.                                     [REQUIRED]

  RESPONSE:
  {
    -request: {
      act: "user_deactivate"
    },
      -response: {
      user_email:  "[email protected]",
      user_zone:   "example.com"
    },
    result: "success",
    msg: "Your new FOOBAR account has been deactivated."
  }
  

2.2.3 - "sub_start" - Activate a subscription. (Optional)

  INPUT:
  user_email    -- Email address of the user.                                                       [REQUIRED]
  user_zone     -- Zone where the subscription is being added.                                      [OPTIONAL]
  sub_plan      -- Type of subscription.                                                            [REQUIRED]

  RESPONSE:
  {
    -request: {
      act: "sub_start"
    },
      -response: {
      user_email:  "[email protected]",
      sub_plan:    "CF_BASIC"
    },
    result: "success",
    msg: "You have been activated on the plan CF_BASIC"
  }
  

2.2.4 - "sub_end" - Deactivate an subscription. (Optional)

  INPUT:
  user_email    -- Email address of the user.                                                       [REQUIRED]
  user_zone     -- Zone where the subscription is being added.                                      [OPTIONAL]
  sub_plan      -- Type of subscription.                                                            [REQUIRED]

  RESPONSE:
  {
    -request: {
      act: "sub_end"
    },
      -response: {
      user_email:  "[email protected]",
      sub_plan:    "CF_BASIC"
    },
    result: "success",
    msg: "you will no longer be charged for the plan CF_BASIC"
  }