CloudFlare App Integration API v1.0 Beta

 

Introduction

CloudFlare App Integration API allows application developers to offer their service to thousands of website owners as part of the CloudFlare application platform.

CloudFlare's application platform can

• automate user provisioning for your service if you respond to the requests from CloudFlare according to the requirements set below
• handle billing for your service and notify your application when a user starts or ends their subscription to your service

Overview

All requests from CloudFlare will terminate at the application developer / service provider's endpoint that handles POST requests sent over a secure connection (HTTPS).

The application must return a JSON response. See below for response format.

Requests from CloudFlare

All requests will contain an act parameter.

The act parameter will have one of the following values

• user_create
• user_deactivate
• sub_start
• sub_end

User Provisioning

For applications that require account creation, CloudFlare will send requests on behalf of the user to reduce friction for first time users.

user_create

A user_create request is sent when the user decides to use the application on their CloudFlare powered website. The application developer should respond to this with any user specific data that needs to be stored for future use of the service.

The request will consist of at least the following parameters:

• 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 Terms of Service for the service. Boolean. [REQUIRED]
• user_tokens -- A JSON encoded map of token names to token values. Specific to each service. [OPTIONAL]

user_deactivate

A user_deactivate request is sent when the user no longer wishes to use the service on their website.

The request will consist of the following parameters:

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

NOTE: It is expected that user may toggle a service on a given zone on or off multiple times.
NOTE: It is optional for the service provider to respond to this API call.

Subscriptions

Implementing subscriptions is optional and is required only when your service offers a subscription model for which CloudFlare handles billing.

Plans offered are mutually agreed upon between CloudFlare and service provider.

sub_start

A sub_start request indicates that a user chose to subscribe to the service.

The request will consist of the following parameters:

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

sub_end

A sub_end request is sent when the user decides to cancel the subscription.

The request will consist of the following parameters:

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

Responding to CloudFlare's Requests

All responses should be JSON formatted.

The response must pass back the act parameter and any other user data that was sent as part of the request.

All responses should include a result string which can be set to "success" or "error" as appropriate.

The response should contain a msg string which should contain a message that will be displayed to the end user.

{
  "request": {
    "act": "user_create",
    "user_email": "[email protected]",
    "user_zone": "example.com"
  },
  "result": "success",
  "msg": "A message that will be displayed to the end user"
  ...
}

The response may also contain a response object that may include one or more of the following parameters (or any other extra params previously agreed upon)

• service_id - the unique ID that was assigned to the user
• service_url - a URL where the user can login and use the service or a link to the service dashboard

{
  "request": {
    "act": "user_create",
    "user_email": "[email protected]",
    "user_zone": "example.com"
  },
  "response": {
	"service_id": "unique_id_assigned_to_user",
	"service_url": "URL where the user can login or a one that takes them to an authenticated session"
  },
  "result": "success",
  "msg": "A message that will be relayed to the end user"
  
}

Test Framwork

If you choose to simulate the requests sent by CloudFlare and test your application's behaviour (which we highly recommend that you do) before integrating with the CloudFlare platform, you can get the test framework (PHP).

Contact

If you have an further questions, send us an email.