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.

A complete, runnable example can be found ​here.

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 ​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 ​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.

app.py

We will be using the Python package called ​`requests_oauthlib`. You can install this package using pip:

pip install -U requests_oauthlib

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', [])