Changes between Initial Version and Version 1 of Guides/Telldus Live API

Timestamp:

Oct 3, 2024, 4:27:57 PM (14 months ago)

Author:

edwin

Comment:

--

Guides/Telldus Live API

@@ +1 @@
+
+== Understanding OAuth 1.0a with Telldus Live!
+
+OAuth 1.0a is an authorization protocol that allows applications to access user data without exposing user credentials.
+
+You can access the Telldus Live! API using OAuth 1.0a for authenticating API requests.
+
+**OAuth 1.0a Flow**
+
+Request Token: Your application requests a temporary token from Telldus.\\
+User Authorization: Redirect the user to Telldus to authorize the application.\\
+Access Token: Exchange the temporary token for an access token.\\
+API Requests: Use the access token to make authenticated API requests.\\
+
+**Telldus Live! OAuth Endpoints**
+
+These are the end points you will need to use to execute the OAuth 1.0a flow:
+
+Request Token: `https://pa-api.telldus.com/oauth/requestToken`\\
+Authorize Token: `https://pa-api.telldus.com/oauth/authorize`\\
+Access Token: `https://pa-api.telldus.com/oauth/accessToken`\\
+
+API Calls: `https://pa-api.telldus.com/{format}/{function}`\\
+where {format} is either "xml" or "json", {function} is the function to call. Please see the [https://pa-api.telldus.com/explore/index Explorer] for a list of available functions.
+
+Calls can be made as either GET or POST\\
+For example. List of available devices and return the data as json:\\
+`curl -X GET "https://pa-api.telldus.com/devices/list?supportedMethods=3&format=json"`
+
+
+**Python example for accessing the Telldus Live API**
+
+The following example shows a very basic implementation using Python to obtain a list of all clients and a list of all devices under your Telldus account.
+
+**Configuration**
+
+First let's define the OAuth consumer key and client secret. You can find both from  [https://pa-api.telldus.com/keys/showToken here], they are called Public key and Private key respectively.
+
+We put all these into a configuration file, let's call it `config.py`:
+{{{
+# Obtain the public and private key from https://pa-api.telldus.com/keys/showToken
+CONSUMER_KEY = 'Public key'
+CONSUMER_SECRET = 'Private key'
+}}}
+
+Then the end points:\\
+
+{{{
+# Defines the API end points
+REQUEST_TOKEN_URL = 'https://pa-api.telldus.com/oauth/requestToken'
+AUTHORIZE_URL = 'https://pa-api.telldus.com/oauth/authorize'
+ACCESS_TOKEN_URL = 'https://pa-api.telldus.com/oauth/accessToken'
+}}}
+
+For the main application, let's call it `app.py`. We will use the python module `requests_oauthlib` to facilitate the OAuth1.0a work flow.
+
+**app.py**
+
+First, we construct a function to setup and return an OAuth 1.0a session:
+
+{{{
+# OAuth1Session setup
+def get_oauth_session(token=None, token_secret=None):
+    return OAuth1Session(
+        client_key=config.CONSUMER_KEY,
+        client_secret=config.CONSUMER_SECRET,
+        resource_owner_key=token,
+        resource_owner_secret=token_secret,
+        callback_uri=config.CALLBACK_URL
+    )
+}}}
+
+Next, we perform the OAuth login process.
+
+To do that, we first obtain an OAuth1 session by calling the above function, then we invoke `fetch_request_token()` to obtain the temporary tokens. We will need these temporary tokens to exchange for the actual access token necessary for the API accesses once we have been authorised.
+
+{{{
+    oauth = get_oauth_session()
+    fetch_response = oauth.fetch_request_token(config.REQUEST_TOKEN_URL)
+    # Save the temporary tokens
+    oauth_token = fetch_response.get('oauth_token')
+    oauth_token_secret = fetch_response.get('oauth_token_secret')
+}}}
+
+Now we have the temporary tokens with us, we will now obtain the authorisation from Telldus.
+
+We configure the OAuth1 session with the authorisation URL and redirect the browser to the authorisation URL `AUTHORIZE_URL`, which would call up the Telldus Live login page where you will be asked to provide your Telldus login ID and password for authentication and authorisation.
+
+{{{
+    authorization_url = oauth.authorization_url(config.AUTHORIZE_URL)
+    redirect(authorization_url)
+}}}
+
+Upon finishing the authorisation (whether it was successful or not), the browser will always be redirected to the `callback_uri` provided in the OAuth1 session. This callback_uri can also be defined in the `config.py` such as `CALLBACK_URL`.
+
+**Handling callback**
+
+Once the authorisation is done, and if it is successful, we could then use the temporary tokens to exchange for the access token.
+
+We can determine if the authorisation was successful or not by inspecting the oauth_verifier:
+
+{{{
+    oauth = get_oauth_session(oauth_token, oauth_token_secret)
+    oauth_response = oauth.parse_authorization_response(request.url)
+    verifier = oauth_response.get('oauth_verifier')
+    if not verifier:
+        print('Authorization failed or was denied.')
+}}}
+
+Now we can exchange for the access token by calling `fetch_access_token()`, and replace the temporary ones with these:
+
+{{{
+    oauth_tokens = oauth.fetch_access_token(config.ACCESS_TOKEN_URL, verifier=verifier)
+    # Replace the temporary tokens with the final ones
+    oauth_token = oauth_tokens.get('oauth_token')
+    oauth_token_secret = oauth_tokens.get('oauth_token_secret')
+}}}
+
+With these two, `oauth_token` and `oauth_token_secret`, we can now access to the Telldus API by calling the appropriate API endpoints.
+
+For example, to list all the devices under your account as JSON:
+
+First we construct the OAuth1 session by passing it our newly obtained tokens as well as the parameter values required for the `devices/list` API. Then we invoke the `get()` function to obtain the list of devices. The returned data will be in JSON:
+
+{{{
+    oauth = get_oauth_session(access_token, access_token_secret)
+    params = {
+        'supportedMethods': 'TURNON|TURNOFF',  # Example parameter
+        'format': 'json'
+    }
+    response = oauth.get("https://pa-api.telldus.com/json/devices/list", params=params)
+    devices = response.json().get('devices', [])
+}}}
+