== 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 [https://developer.telldus.com/wiki/Examples/PA-API%20Python%20Example 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 [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`.

**app.py**

We will be using the Python package called [https://pypi.org/project/requests-oauthlib/ `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', [])
}}}