Optimized Partner API

Overview

This article is intended for CloudFlare Optimized Hosting Partners. End-users must utilize the Client API. All Railgun API requests must include a Host API token as a request parameter. You can apply for an API key or read more about CloudFlare Hosting Partner programs here. All API requests should be directed at ‘https://www.cloudflare.com/‘.

Multiple Railguns may be added to a CloudFlare host account. Only one registered and activated Railgun may be used per domain. Railgun can be load-balanced and multiple Railgun daemons can be used per activated public IP and token. There is no need to register each Railgun daemon if they share a public IP.

All API methods may be performed either as GET requests that include query string parameters or POST requests. The return status of the API request and any relevant errors messages are within the returned JSON response body. The result member indicates success or failure and the msg member contains further details if applicable.

Creation, Activation, and Deletion

Creating and activating a Railgun requires two API calls. First, a Railgun must be initialized and then activated using the init and activate calls respectively. The activation API call is made by Railgun when the daemon is started and does not need to be made by a user.

The response body of the init API call will contain the activation token (rtkn) required activation. Set activation.token within the Railgun configuration file to the value of rtkn from the API call response.

POST /api/v2/railgun/init

Create a Railgun. If request is successful, a new Railgun is added to a host account and placed in initializing status (INI).

Form Parameters:
 
  • host_key – Host API key
  • name – Name of Railgun (optional)
  • pubname – Name of Railgun shown to users (optional)

Example request:

POST /api/v2/railgun/init HTTP/1.1
Host: www.cloudflare.com
Accept: */*
Content-Type: application/x-www-form-urlencoded

Example form parameters:

host_key=e111dff66d1fddfda6a888c9992d4366
name=my-railgun
pubname=My%20Railgun

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
     "msg": null,
     "response": {
         "act": "railgun_init",
         "railgun_id": "1",
         "railgun_name": "RG_a1b2c3d4e5f6g7h8i9j0k1",
         "railgun_status": "INI",
         "rtkn": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5pp"
     },
     "result": "success"
}
GET /api/v2/railgun/init

Create a Railgun. If request is successful, a new Railgun is added to a host account and placed in initializing status (INI).

Query Parameters:
 
  • host_key – Host API key
  • name – Name of Railgun (optional)
  • pubname – Name of Railgun shown to users (optional)

Example request:

GET /api/v2/railgun/init?host_key=&pubname=&name= HTTP/1.1
Host: www.cloudflare.com
Accept: */*
Content-Type: application/x-www-form-urlencoded

Example query string parameters:

host_key=e111dff66d1fddfda6a888c9992d4366
name=my-railgun
pubname=My%20Railgun

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
     "msg": null,
     "response": {
         "act": "railgun_init",
         "railgun_id": "1",
         "railgun_name": "RG_a1b2c3d4e5f6g7h8i9j0k1",
         "railgun_status": "INI",
         "rtkn": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5pp"
     },
     "result": "success"
}

POST /api/v2/railgun/delete

Delete a Railgun. If request is successful, the Railgun with a token matching rtkn is removed from the account and set to deleted status (D).

Form Parameters:
 
  • host_key – Host API key
  • rtkn – Railgun token

Example request:

POST /api/v2/railgun/delete HTTP/1.1
Host: www.cloudflare.com
Accept: */*
Content-Type: application/x-www-form-urlencoded

Example form parameters:

host_key=e111dff66d1fddfda6a888c9992d4366
rtkn=7h8i9j0k1l2m3n4o5p6q7r8id9h0j1l

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
     "msg": null,
     "response": {
         "act": "railgun_delete",
         "railgun_id": "1",
     },
     "result": "success"
}
GET /api/v2/railgun/delete

Delete a Railgun. If request is successful, the Railgun with a token matching rtkn is removed from the account and set to deleted status (D).

Query Parameters:
 
  • host_key – Host API key
  • rtkn – Railgun token

Example request:

GET /api/v2/railgun/delete?host_key=&rtkn= HTTP/1.1
Host: www.cloudflare.com
Accept: */*
Content-Type: application/x-www-form-urlencoded

Example query string parameters:

host_key=e111dff66d1fddfda6a888c9992d4366
rtkn=7h8i9j0k1l2m3n4o5p6q7r8id9h0j1l

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
     "msg": null,
     "response": {
         "act": "railgun_delete",
         "railgun_id": "1",
     },
     "result": "success"
}

Listing and Viewing Railgun Details

The following API calls can be used to determine details and the status or one or more Railguns assigned to an account. These calls are sometimes needed to determine the unique rtkn or id assigned to a Railgun.

POST /api/v2/railgun/host_get_all

Assign a Railgun to a domain

Form Parameters:
 
  • host_key – Host API key

Example request:

POST /api/v2/railgun/host_get_all HTTP/1.1
Host: www.cloudflare.com
Accept: */*
Content-Type: application/x-www-form-urlencoded

Example form parameters:

host_key=e111dff66d1fddfda6a888c9992d4366

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "msg": null,
    "response": {
        "act": "railgun_host_get_all",
        "railguns": {
            "count": 5,
            "objs": [
                {
                    "cdate": "2012-10-27 16:34:37.718746-07",
                    "edate": "2012-11-06 13:02:16.153332-08",
                    "props": {
                        "build": "2012-10-27-1257",
                        "number": "2.6.0",
                        "revision": "ff3f8f25f5238de327cf34059659de0738399176"
                    },
                    "railgun_activated_on": "2012-11-06 13:02:16.122355-08",
                    "railgun_api_key": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5pp",
                    "railgun_deleted_on": null,
                    "railgun_host_id": null,
                    "railgun_id": "1",
                    "railgun_ip": null,
                    "railgun_mode": "1",
                    "railgun_name": "RG_100f5777999990edb60d2db56627f9",
                    "railgun_port": "2408",
                    "railgun_pubname": "Railgun for example.com",
                    "railgun_rec_id": "100",
                    "railgun_rec_name": "rg-d65dfffff666a77fd3dea2a7cfeede90.port2408.net",
                    "railgun_status": "V",
                    "railgun_tag": "a18bbbbc555f4g6h2i8j222l711n",
                    "railgun_type": "user",
                    "railgun_user_id": "1000"
                },
                {
                    "cdate": "2012-11-02 00:03:33.17205-07",
                    "edate": "2012-11-02 00:03:33.17205-07",
                    "props": {
                        "build": null,
                        "number": null,
                        "revision": null
                    },
                    "railgun_activated_on": null,
                    "railgun_api_key": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5pp",
                    "railgun_deleted_on": null,
                    "railgun_host_id": null,
                    "railgun_id": "178",
                    "railgun_ip": null,
                    "railgun_mode": "0",
                    "railgun_name": "RG_000f7777999690edb60d2db56627f9",
                    "railgun_port": "2408",
                    "railgun_pubname": "Railgun for mydomain.com",
                    "railgun_rec_id": null,
                    "railgun_rec_name": null,
                    "railgun_status": "INI",
                    "railgun_tag": "d18bbbbc555f4g6h2i8j222l711n",
                    "railgun_type": "user",
                    "railgun_user_id": "1000"
                }
            ]
        }
    },
    "result": "success"
}
GET /api/v2/railgun/host_get_all

Assign a Railgun to a domain

Query Parameters:
 
  • host_key – Host API key

Example request:

GET /api/v2/railgun/host_get_all?host_key= HTTP/1.1
Host: www.cloudflare.com
Accept: */*
Content-Type: application/x-www-form-urlencoded

Example query string parameters:

host_key=e111dff66d1fddfda6a888c9992d4366

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "msg": null,
    "response": {
        "act": "railgun_host_get_all",
        "railguns": {
            "count": 5,
            "objs": [
                {
                    "cdate": "2012-10-27 16:34:37.718746-07",
                    "edate": "2012-11-06 13:02:16.153332-08",
                    "props": {
                        "build": "2012-10-27-1257",
                        "number": "2.6.0",
                        "revision": "ff3f8f25f5238de327cf34059659de0738399176"
                    },
                    "railgun_activated_on": "2012-11-06 13:02:16.122355-08",
                    "railgun_api_key": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5pp",
                    "railgun_deleted_on": null,
                    "railgun_host_id": null,
                    "railgun_id": "1",
                    "railgun_ip": null,
                    "railgun_mode": "1",
                    "railgun_name": "RG_100f5777999990edb60d2db56627f9",
                    "railgun_port": "2408",
                    "railgun_pubname": "Railgun for example.com",
                    "railgun_rec_id": "100",
                    "railgun_rec_name": "rg-d65dfffff666a77fd3dea2a7cfeede90.port2408.net",
                    "railgun_status": "V",
                    "railgun_tag": "a18bbbbc555f4g6h2i8j222l711n",
                    "railgun_type": "user",
                    "railgun_user_id": "1000"
                },
                {
                    "cdate": "2012-11-02 00:03:33.17205-07",
                    "edate": "2012-11-02 00:03:33.17205-07",
                    "props": {
                        "build": null,
                        "number": null,
                        "revision": null
                    },
                    "railgun_activated_on": null,
                    "railgun_api_key": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5pp",
                    "railgun_deleted_on": null,
                    "railgun_host_id": null,
                    "railgun_id": "178",
                    "railgun_ip": null,
                    "railgun_mode": "0",
                    "railgun_name": "RG_000f7777999690edb60d2db56627f9",
                    "railgun_port": "2408",
                    "railgun_pubname": "Railgun for mydomain.com",
                    "railgun_rec_id": null,
                    "railgun_rec_name": null,
                    "railgun_status": "INI",
                    "railgun_tag": "d18bbbbc555f4g6h2i8j222l711n",
                    "railgun_type": "user",
                    "railgun_user_id": "1000"
                }
            ]
        }
    },
    "result": "success"
}

POST /api/v2/railgun/zone_conn_get_active

List all active Railgun connections for a domain.

Form Parameters:
 
  • email – User account email
  • tkn – User API token

Example request:

POST /api/v2/railgun/zone_conn_get_active HTTP/1.1
Host: www.cloudflare.com
Accept: */*
Content-Type: application/x-www-form-urlencoded

Example form parameters:

host_key=e111dff66d1fddfda6a888c9992d4366
z=example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "msg": null,
    "response": {
        "act": "railgun_zone_conn_get_active",
        "railgun_conn": {
            "obj": {
                    "railgun_conn_id": "2",
                    "railgun_id": "123",
                    "railgun_conn_status": "V",
                    "railgun_conn_mode": "1",
                    "railgun_enabled": "t",
                }
        }
    },
    "result": "success"
}
GET /api/v2/railgun/zone_conn_get_active

List all active Railgun connections for a domain.

Form Parameters:
 
  • email – User account email
  • tkn – User API token

Example request:

GET /api/v2/railgun/zone_conn_get_active?host_key=&z= HTTP/1.1
Host: www.cloudflare.com
Accept: */*
Content-Type: application/x-www-form-urlencoded

Example query string parameters:

host_key=e111dff66d1fddfda6a888c9992d4366
z=example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "msg": null,
    "response": {
        "act": "railgun_zone_conn_get_active",
        "railgun_conn": {
            "obj": {
                    "railgun_conn_id": "2",
                    "railgun_id": "123",
                    "railgun_conn_status": "V",
                    "railgun_conn_mode": "1",
                    "railgun_enabled": "t",
                }
        }
    },
    "result": "success"
}

Connections, Enabling and Disabling

After a Railgun has been activated, it can be exposed to a particular domain with the suggestion_set API call. suggestion_set also accepts the auto_enabled parameter to assign and enable Railgun for the domain globally in a single API call. If auto_enabled is not set to 1, then the connection needed to enable Railgun for the domain must be made manually using the conn_set method. conn_setmode_enabled and conn_setmode_disabled can be used to toggle Railgun on or off for the domain globally. zone_conn_get_active can be used to view active Railgun connections.

POST /api/v2/railgun/suggestion_set

Expose a verified Railgun to a domain via the CloudFlare Settings user-interface. This method allows an end-user to select and enable the specified Railgun within the CloudFlare Settings user-interface. If auto_enabled is set to 0, it is also necessary to perform a conn_set for the Railgun in order to setup a connection with the domain.

Form Parameters:
 
  • host_key – Host API key
  • z – Domain name
  • rtkn – Railgun token
  • auto_enabled – Railgun operation mode, 1 for active 0 for inactive

Example request:

POST /api/v2/railgun/suggestion_set HTTP/1.1
Host: www.cloudflare.com
Accept: */*
Content-Type: application/x-www-form-urlencoded

Example form parameters:

host_key=e111dff66d1fddfda6a888c9992d4366
rtkn=7h8i9j0k1l2m3n4o5p6q7r8id9h0j1l
auto_enabled=0
z=example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
     "msg": null,
     "response": {
        "act": "railgun_suggest",
        "railgun_id": "1",
    },
    "result": "success"
}
GET /api/v2/railgun/suggestion_set

Expose a verified Railgun to a domain via the CloudFlare Settings user-interface. This method allows an end-user to select and enable the specified Railgun within the CloudFlare Settings user-interface. If auto_enabled is set to 0, it is also necessary to perform a conn_set for the Railgun in order to setup a connection with the domain.

Query Parameters:
 
  • host_key – Host API key
  • z – Domain name
  • rtkn – Railgun token
  • auto_enabled – Railgun operation mode, 1 for active 0 for inactive

Example request:

GET /api/v2/railgun/suggestion_set?host_key=&rtkn=&z=&mode= HTTP/1.1
Host: www.cloudflare.com
Accept: */*
Content-Type: application/x-www-form-urlencoded

Example query string parameters:

host_key=e111dff66d1fddfda6a888c9992d4366
rtkn=7h8i9j0k1l2m3n4o5p6q7r8id9h0j1l
auto_enabled=0
z=example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
     "msg": null,
     "response": {
        "act": "railgun_suggest",
        "railgun_id": "1",
    },
    "result": "success"
}

POST /api/v2/railgun/conn_set

Establish a connection between a domain and a Railgun without requiring the domain’s user to utilize the CloudFlare Settings user-interface to change or deactivate it. The mode parameter can be set to 1 in order to enable the Railgun globally if conn_set succeeds.

Form Parameters:
 
  • host_key – Host API key
  • z – Domain name
  • rtkn – Railgun token
  • mode – Railgun operation mode, 1 for active 0 for inactive

Example request:

POST /api/v2/railgun/conn_set HTTP/1.1
Host: www.cloudflare.com
Accept: */*
Content-Type: application/x-www-form-urlencoded

Example form parameters:

host_key=e111dff66d1fddfda6a888c9992d4366
rtkn=7h8i9j0k1l2m3n4o5p6q7r8id9h0j1l
mode=0
z=example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
     "msg": null,
     "response": {
        "act": "railgun_conn_set",
        "railgun_conn_id": "1",
        "railgun_rec_name": "rg-d65dfffff666a77fd3dea2a7cfeede90.port2408.net"
    },
    "result": "success"
}
GET /api/v2/railgun/conn_set

Establish a connection between a domain and a Railgun without requiring the domain’s user to utilize the CloudFlare Settings user-interface to change or deactivate it. The mode parameter can be set to 1 in order to enable the Railgun globally if conn_set succeeds.

Query Parameters:
 
  • host_key – Host API key
  • z – Domain name
  • rtkn – Railgun token
  • mode – Railgun operation mode, 1 for active 0 for inactive

Example request:

GET /api/v2/railgun/conn_set?host_key=&rtkn=&z=&mode= HTTP/1.1
Host: www.cloudflare.com
Accept: */*
Content-Type: application/x-www-form-urlencoded

Example query string parameters:

host_key=e111dff66d1fddfda6a888c9992d4366
rtkn=7h8i9j0k1l2m3n4o5p6q7r8id9h0j1l
mode=0
z=example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
     "msg": null,
     "response": {
        "act": "railgun_conn_set",
        "railgun_conn_id": "1",
        "railgun_rec_name": "rg-d65dfffff666a77fd3dea2a7cfeede90.port2408.net"
    },
    "result": "success"
}

POST /api/v2/railgun/conn_setmode_enabled

Enable a Railgun. If request is successful, the specified Railgun will be enabled and traffic for the specified domain will be proxied through Railgun.

Form Parameters:
 
  • host_key – Host API key
  • z – Domain name
  • rtkn – Railgun token

Example request:

POST /api/v2/railgun/conn_setmode_enabled HTTP/1.1
Host: www.cloudflare.com
Accept: */*
Content-Type: application/x-www-form-urlencoded

Example form parameters:

host_key=e111dff66d1fddfda6a888c9992d4366
rtkn=7h8i9j0k1l2m3n4o5p6q7r8id9h0j1l
z=example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
     "msg": null,
     "response": {
         "act": "railgun_conn_setmode_enabled",
         "railgun_id": "1"
     },
     "result": "success"
}
GET /api/v2/railgun/conn_setmode_enabled

Enable a Railgun. If request is successful, the specified Railgun will be enabled and traffic for the specified domain will be proxied through Railgun.

Query Parameters:
 
  • host_key – Host API key
  • z – Domain name
  • rtkn – Railgun token

Example request:

GET /api/v2/railgun/conn_setmode_enabled?host_key=&rtkn=&z= HTTP/1.1
Host: www.cloudflare.com
Accept: */*
Content-Type: application/x-www-form-urlencoded

Example query string parameters:

host_key=e111dff66d1fddfda6a888c9992d4366
rtkn=7h8i9j0k1l2m3n4o5p6q7r8id9h0j1l
z=example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
     "msg": null,
     "response": {
         "act": "railgun_conn_setmode_enabled",
         "railgun_id": "1"
     },
     "result": "success"
}

POST /api/v2/railgun/conn_setmode_disabled

Disable a Railgun. If request is successful, the specified Railgun will be disabled and traffic for the specified domain will no longer use Railgun.

Form Parameters:
 
  • host_key – Host API key
  • z – Domain name
  • rtkn – Railgun token

Example request:

POST /api/v2/railgun/conn_setmode_disabled HTTP/1.1
Host: www.cloudflare.com
Accept: */*
Content-Type: application/x-www-form-urlencoded

Example form parameters:

host_key=e111dff66d1fddfda6a888c9992d4366
rtkn=7h8i9j0k1l2m3n4o5p6q7r8id9h0j1l
z=example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
     "msg": null,
     "response": {
         "act": "railgun_conn_setmode_disabled",
         "railgun_id": "1"
     },
     "result": "success"
}
GET /api/v2/railgun/conn_setmode_disabled

Disable a Railgun. If request is successful, the specified Railgun will be disabled and traffic for the specified domain will no longer use Railgun.

Query Parameters:
 
  • host_key – Host API key
  • z – Domain name
  • rtkn – Railgun token

Example request:

GET /api/v2/railgun/conn_setmode_disabled?host_key=&rtkn=&z= HTTP/1.1
Host: www.cloudflare.com
Accept: */*
Content-Type: application/x-www-form-urlencoded

Example query string parameters:

host_key=e111dff66d1fddfda6a888c9992d4366
rtkn=7h8i9j0k1l2m3n4o5p6q7r8id9h0j1l
z=example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
     "msg": null,
     "response": {
         "act": "railgun_conn_setmode_disabled",
         "railgun_id": "1"
     },
     "result": "success"
}

POST /api/v2/railgun/conn_delete

Remove a connection between a domain and a Railgun. This API call will allow a connected Railgun to be assigned to a different domain. Removing the connection of an enabled Railgun and domain will disable Railgun for the domain until a new connection is made with conn_set.

Form Parameters:
 
  • host_key – Host API key
  • z – Domain name
  • rtkn – Railgun token

Example request:

POST /api/v2/railgun/conn_delete HTTP/1.1
Host: www.cloudflare.com
Accept: */*
Content-Type: application/x-www-form-urlencoded

Example form parameters:

host_key=e111dff66d1fddfda6a888c9992d4366
rtkn=7h8i9j0k1l2m3n4o5p6q7r8id9h0j1l
z=example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
     "msg": null,
     "response": {
         "act": "railgun_conn_delete",
         "railgun_id": "1"
     },
     "result": "success"
}
GET /api/v2/railgun/conn_delete

Remove a connection between a domain and a Railgun. This API call will allow a connected Railgun to be assigned to a different domain. Removing the connection of an enabled Railgun and domain will disable Railgun for the domain until a new connection is made with conn_set.

Query Parameters:
 
  • host_key – Host API key
  • z – Domain name
  • rtkn – Railgun token

Example request:

GET /api/v2/railgun/conn_delete?host_key=&rtkn=&z= HTTP/1.1
Host: www.cloudflare.com
Accept: */*
Content-Type: application/x-www-form-urlencoded

Example query string parameters:

host_key=e111dff66d1fddfda6a888c9992d4366
rtkn=7h8i9j0k1l2m3n4o5p6q7r8id9h0j1l
z=example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
     "msg": null,
     "response": {
         "act": "railgun_conn_delete",
         "railgun_id": "1"
     },
     "result": "success"
}

Making Railguns available to domains via IP range(s)

It is possible to make a Railgun available to domains via IP ranges. This can be done by setting one or more IP range(s) that a Railgun will use. Once the Railgun IP Range(s) have been set, any domains that have origin IP(s) that fall within a Railgun’s IP Range(s) will have the ability to select and enable the Railgun.

POST /api/v2/railgun/ipr_set

Set the IP range(s) for a Railgun. This will expose the railgun to domains whose origin IP(s) are contained within the Railgun’s IP range.

The ipr holds IPv4 or IPv6 host addresses, and optionally their subnet, all in one field. The subnet is represented by the number of network address bits present in the host address (the “netmask”). If the netmask is 32 AND the address is IPv4, then the value does not indicate a subnet, only a single host. In IPv6, the address length is 128 bits, so 128 bits specify a unique host address.

The input format for this type is address/y where address is an IPv4 or IPv6 address and y is the number of bits in the netmask. If the /y portion is missing, the netmask is 32 for IPv4 and 128 for IPv6, so the value represents just a single host. On display, the /y portion is suppressed if the netmask specifies a single host.

For internal reasons, CloudFlare restricts the netmask range of 8 < netmask < 32 for IPv4 and 112 < netmask < 128 for IPv6.

Form Parameters:
 
  • rtkn – Railgun token
  • ipr – One or more Railgun IP addresses/ranges. Use JSON array format.

Example request:

POST /api/v2/railgun/ipr_set HTTP/1.1
Host: www.cloudflare.com
Accept: */*
Content-Type: application/x-www-form-urlencoded

Example form parameters:

rtkn=7h8i9j0k1l2m3n4o5p6q7r8id9h0j1l
ipr=["203.0.0.0/8","208.0.0.0/8","207.0.0.7","BE81::02C3:B44F:FE1E:8329/112"]

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
     "msg": null,
     "response": {
        "act": "railgun_ipr_set",
        "railgun_id": "1079",
    },
    "result": "success"
}

Using cURL with the API

Here is how to create, activate, assign, and enable a Railgun using cURL and the Optimized Partner API. First, look up the user_key for the domain to add a Railgun to. This can be done using the user_lookup Host API method and the user’s email address or unique ID:

$ curl -s 'https://api.cloudflare.com/host-gw.html?act=user_lookup&host_key=YOUR_HOST_API_KEY&[email protected]'

{
    "msg": null,
    "request": {
        "act": "user_lookup",
        "cloudflare_email": "[email protected]"
    },
    "response": {
        "cloudflare_email": "[email protected]",
        "hosted_zones": [
            "example.com"
        ],
        "unique_id": "UNIQUE_ID (CAN BE USED IN PLACE OF USER'S EMAIL)",
        "user_api_key": "USER_API_KEY (NOT USED FOR RAILGUN)",
        "user_authed": true,
        "user_exists": true,
        "user_key": "UNIQUE_USER_KEY_OF_32_CHARACTERS"
    },
    "result": "success"
}

Next, call the init API method to create a new Railgun using the host_key and user_key:

$ curl 'https://www.cloudflare.com/api/v2/railgun/init?host_key=YOUR_HOST_API_KEY&pubname=My%20Railgun'

{
    "msg": null,
    "response": {
        "act": "railgun_init",
        "railgun_id": "1",
        "railgun_name": "GENERATED_OR_SPECIFIED_RG_NAME",
        "railgun_status": "INI",
        "rtkn": "30_CHARACTER_RTKN"
    },
    "result": "success"
}

The Railgun daemon should then be started so that it may complete the activation process, which should be logged via syslog after startup:

$  tail -f /var/log/messages
Oct 27 22:29:41 www railgun[Activation]: Activation POST completed.
Oct 27 22:29:41 www railgun[Activation]: Assigned Railgun ID: 1
Oct 27 22:29:41 www railgun[Activation]: Acquired cert from server

Next, the suggestion_set method is called with auto_enabled set to 0 in order to expose the Railgun to the domain. Setting auto_enabled to 0 will not enable Railgun for the domain, it will only expose the Railgun instance to the domain within CloudFlare Settings. To expose, associate, and enable Railgun in a single API call, set auto_enabled to 1.

$ curl 'https://www.cloudflare.com/api/v2/railgun/suggestion_set?host_key=YOUR_HOST_API_KEY&z=example.com&rtkn=30_CHARACTER_RTKN&auto_enabled=0'

{
    "msg": null,
    "response": {
        "act": "railgun_suggest",
        "railgun_id": "1",
    },
    "result": "success"
}

The user should now be able to see the Railgun configuration dropdown menu within their CloudFlare Settings panel. The user can now test and enable Railgun themselves. If auto_enabled had been set to 1, the following conn_set call is not necessary and would’ve been performed automatically.

Finally, the conn_set method is called to associate the Railgun with the domain and create the necessary port2408.net DNS records and SSL certificate. It is possible to test Railgun without enabling it using a special HTTP header. More details on testing with the port2408.net hostname (railgun_rec_name) in the installation documentation.

$ curl 'https://www.cloudflare.com/api/v2/railgun/conn_set?host_key=YOUR_HOST_API_KEY&z=example.com&rtkn=30_CHARACTER_RTKN&mode=0'

{
    "msg": null,
    "response": {
        "act": "railgun_conn_set",
        "railgun_conn_id": "2",
        "railgun_rec_name": "rg-ffffffff1111111111111111.port2408.net"
    },
    "result": "success"
}