Merge pull request cloudflare#76 from nijel/patch-1

Add support for API Tokens

CloudFlare/cloudflare.py

@@ -49,6 +49,14 @@ def call_with_no_auth(self, method, parts,
                               identifier1, identifier2, identifier3,
                               params, data, files)
 
+        def _add_auth_headers(self, headers):
+            """ Add authentication headers """
+            if self.email:
+                headers['X-Auth-Email'] = self.email
+                headers['X-Auth-Key'] = self.token
+            else:
+                headers['Authorization'] = 'Bearer {}'.format(self.token)
+
         def call_with_auth(self, method, parts,
                            identifier1=None, identifier2=None, identifier3=None,
                            params=None, data=None, files=None):
@@ -58,10 +66,9 @@ def call_with_auth(self, method, parts,
                 raise CloudFlareAPIError(0, 'no email and/or token defined')
             headers = {
                 'User-Agent': self.user_agent,
-                'X-Auth-Email': self.email,
-                'X-Auth-Key': self.token,
                 'Content-Type': 'application/json'
             }
+            self._add_auth_headers(headers)
             if type(data) == str:
                 # passing javascript vs JSON
                 headers['Content-Type'] = 'application/javascript'
@@ -83,10 +90,9 @@ def call_with_auth_unwrapped(self, method, parts,
                 raise CloudFlareAPIError(0, 'no email and/or token defined')
             headers = {
                 'User-Agent': self.user_agent,
-                'X-Auth-Email': self.email,
-                'X-Auth-Key': self.token,
                 'Content-Type': 'application/json'
             }
+            self._add_auth_headers(headers)
             if type(data) == str:
                 # passing javascript vs JSON
                 headers['Content-Type'] = 'application/javascript'

README.md

@@ -172,8 +172,8 @@ if __name__ == '__main__':
 
 When you create a **CloudFlare** class you can pass up to four parameters.
 
- * Account email
- * Account API key
+ * API Token or API Key
+ * Account email (only if an API Key is being used)
  * Optional Origin-CA Certificate Token
  * Optional Debug flag (True/False)
 
@@ -186,20 +186,25 @@ import CloudFlare
     # A minimal call with debug enabled
     cf = CloudFlare.CloudFlare(debug=True))
 
-    # A full blown call with passed basic account information
+    # An authenticated call using an API Token (note the missing email)
+    cf = CloudFlare.CloudFlare(token='00000000000000000000000000000000')
+
+    # An authenticated call using an API Key
     cf = CloudFlare.CloudFlare(email='[email protected]', token='00000000000000000000000000000000')
 
-    # A full blown call with passed basic account information and CA-Origin info
+    # An authenticated call using an API Key and CA-Origin info
     cf = CloudFlare.CloudFlare(email='[email protected]', token='00000000000000000000000000000000', certtoken='v1.0-...')
 ```
 
 If the account email and API key are not passed when you create the class, then they are retrieved from either the users exported shell environment variables or the .cloudflare.cfg or ~/.cloudflare.cfg or ~/.cloudflare/cloudflare.cfg files, in that order.
 
+If you're using an API Token, any `cloudflare.cfg` file must not contain an `email` attribute and the `CF_API_EMAIL` environment variable must be unset, otherwise the token will be treated as a key and will throw an error.
+
 There is one call that presently doesn't need any email or token certification (the */ips* call); hence you can test without any values saved away.
 
 ### Using shell environment variables
 ```bash
-$ export CF_API_EMAIL='[email protected]'
+$ export CF_API_EMAIL='[email protected]' # Do not set if using an API Token
 $ export CF_API_KEY='00000000000000000000000000000000'
 $ export CF_API_CERTKEY='v1.0-...'
 $
@@ -212,7 +217,7 @@ These are optional environment variables; however, they do override the values s
 ```bash
 $ cat ~/.cloudflare/cloudflare.cfg
 [CloudFlare]
-email = [email protected]
+email = [email protected] # Do not set if using an API Token
 token = 00000000000000000000000000000000
 certtoken = v1.0-...
 extras =

README.rst

@@ -196,8 +196,8 @@ Providing Cloudflare Username and API Key
 When you create a **CloudFlare** class you can pass up to four
 parameters.
 
--  Account email
--  Account API key
+-  API Token or API Key
+-  Account email (only if an API Key is being used)
 -  Optional Origin-CA Certificate Token
 -  Optional Debug flag (True/False)
 
@@ -211,17 +211,25 @@ parameters.
         # A minimal call with debug enabled
         cf = CloudFlare.CloudFlare(debug=True))
 
-        # A full blown call with passed basic account information
+        # An authenticated call using an API Token (note the missing email)
+        cf = CloudFlare.CloudFlare(token='00000000000000000000000000000000')
+
+        # An authenticated call using an API Key
         cf = CloudFlare.CloudFlare(email='[email protected]', token='00000000000000000000000000000000')
 
-        # A full blown call with passed basic account information and CA-Origin info
+        # An authenticated call using an API Key and CA-Origin info
         cf = CloudFlare.CloudFlare(email='[email protected]', token='00000000000000000000000000000000', certtoken='v1.0-...')
 
 If the account email and API key are not passed when you create the
 class, then they are retrieved from either the users exported shell
 environment variables or the .cloudflare.cfg or ~/.cloudflare.cfg or
 ~/.cloudflare/cloudflare.cfg files, in that order.
 
+If you're using an API Token, any ``cloudflare.cfg`` file must not
+contain an ``email`` attribute and the ``CF_API_EMAIL`` environment
+variable must be unset, otherwise the token will be treated as a key
+and will throw an error.
+
 There is one call that presently doesn't need any email or token
 certification (the */ips* call); hence you can test without any values
 saved away.
@@ -231,7 +239,7 @@ Using shell environment variables
 
 .. code:: bash
 
-    $ export CF_API_EMAIL='[email protected]'
+    $ export CF_API_EMAIL='[email protected]' # Do not set if using an API Token
     $ export CF_API_KEY='00000000000000000000000000000000'
     $ export CF_API_CERTKEY='v1.0-...'
     $
@@ -246,7 +254,7 @@ Using configuration file to store email and keys
 
     $ cat ~/.cloudflare/cloudflare.cfg
     [CloudFlare]
-    email = [email protected]
+    email = [email protected] # Do not set if using an API Token
     token = 00000000000000000000000000000000
     certtoken = v1.0-...
     extras =