Understanding OAuth 2.0 with Telldus Live!

OAuth 2.0 is an authorization framework that allows applications to access user data without exposing user credentials on every API request. Instead, your application obtains an access token and uses it to authenticate calls to the Telldus Live! API.

You can access the Telldus Live! API using OAuth 2.0 with the Resource Owner Password Credentials grant (also known as the *password grant*). This grant type is suited for trusted applications where the user provides their Telldus Live! username and password directly to your application.

A complete, runnable example can be found [here](Examples-PA-API-OAuth2-Python-Example.md).

OAuth 2.0 Flow

The password grant flow used by Telldus Live! consists of the following steps:

1. Obtain Client Credentials: Register your application and obtain a Client ID and Client Secret from the Telldus developer portal.
2. Request Tokens: Your application sends the user's Telldus Live! username and password, together with your client credentials, to the token endpoint.
3. Receive Tokens: Telldus returns an access token and a refresh token.
4. API Requests: Include the access token as a Bearer token in the Authorization header when calling API endpoints.
5. Refresh (optional): When the access token expires, use the refresh token to obtain a new access token without asking the user for their password again.

## Telldus Live! OAuth2 Endpoints

These are the endpoints you will need to use for the OAuth 2.0 flow and API access:

Token endpoint:

https://pa-api.telldus.com/oauth2/accessToken

API calls:

https://pa-api.telldus.com/oauth2/{function}

where {function} is the API function to call (for example devices/list or device/info).

An alternative production host is also available:

https://api.telldus.com/oauth2/{function}

Calls can be made as either GET or POST. Many endpoints accept a format query parameter set to either json or xml.

For example, to list devices and return the data as JSON:

curl -X GET "https://pa-api.telldus.com/oauth2/devices/list?supportedMethods=65535&format=json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Please see the [API Explorer](​https://pa-api.telldus.com/) for a list of available functions.

## Obtaining Client Credentials

You can obtain your Client ID and Client Secret from the Telldus developer portal. These correspond to the Public key and Private key shown at:

https://pa-api.telldus.com/keys/showToken

Store these values securely. Do not commit them to public source code repositories.

Python Example for Accessing the Telldus Live API

The following example shows a basic implementation using Python to obtain OAuth 2.0 tokens and retrieve a list of devices under your Telldus account.

Configuration

First, define the OAuth client ID and client secret. You can find both from ​here; they are called Public key and Private key respectively.

We put these into a configuration file, let's call it config.py:

# Obtain the client ID and client secret from https://pa-api.telldus.com/keys/showToken
CLIENT_ID = 'Your client ID (Public key)'
CLIENT_SECRET = 'Your client secret (Private key)'

# Default Telldus Live! account credentials (optional)
USERNAME = 'your@email.com'
PASSWORD = 'your_password'

Then the endpoints:

# Defines the OAuth2 and API endpoints
TOKEN_URL = 'https://pa-api.telldus.com/oauth2/accessToken'
API_BASE_URL = 'https://pa-api.telldus.com/oauth2'

# Scope requested during token exchange
SCOPE = 'live-app'

For the main application, let's call it app.py.

app.py

We will be using the Python package called requests. You can install this package using pip:

pip install -U requests

First, we construct a function to obtain OAuth 2.0 access and refresh tokens:

import requests
import config

def obtain_tokens(username, password):
    payload = {
        'grant_type': 'password',
        'username': username,
        'password': password,
        'scope': config.SCOPE,
        'client_id': config.CLIENT_ID,
        'client_secret': config.CLIENT_SECRET
    }
    headers = {
        'Content-Type': 'application/x-www-form-urlencoded',
        'User-Agent': 'MyTelldusApp/1.0'
    }
    response = requests.post(config.TOKEN_URL, data=payload, headers=headers)
    response.raise_for_status()
    token_data = response.json()
    return token_data.get('access_token'), token_data.get('refresh_token')

Next, we obtain the tokens using the Telldus Live! username and password:

    access_token, refresh_token = obtain_tokens(config.USERNAME, config.PASSWORD)

With the access token, we can now access the Telldus API by calling the appropriate API endpoints.

For example, to list all devices under your account as JSON:

First we construct the request URL and set the Bearer token in the Authorization header. Then we invoke the get() function to obtain the list of devices. The returned data will be in JSON:

    headers = {
        'Authorization': f'Bearer {access_token}',
        'User-Agent': 'MyTelldusApp/1.0'
    }
    params = {
        'supportedMethods': 65535,
        'format': 'json'
    }
    response = requests.get(
        f"{config.API_BASE_URL}/devices/list",
        headers=headers,
        params=params
    )
    devices = response.json().get('device', [])

Refreshing an Access Token

When an access token expires, you can request a new one using the refresh token:

def refresh_access_token(refresh_token):
    payload = {
        'grant_type': 'refresh_token',
        'refresh_token': refresh_token,
        'client_id': config.CLIENT_ID,
        'client_secret': config.CLIENT_SECRET
    }
    headers = {
        'Content-Type': 'application/x-www-form-urlencoded',
        'User-Agent': 'MyTelldusApp/1.0'
    }
    response = requests.post(config.TOKEN_URL, data=payload, headers=headers)
    response.raise_for_status()
    token_data = response.json()
    return token_data.get('access_token'), token_data.get('refresh_token')

Example: Turn a Device On or Off

Once authenticated, you can control devices by calling the appropriate endpoint with the device ID:

    device_id = 12345678
    response = requests.get(
        f"{config.API_BASE_URL}/device/turnOn",
        headers=headers,
        params={'id': device_id}
    )

Replace turnOn with turnOff to switch a device off.

OAuth 2.0 vs OAuth 1.0a

Telldus Live! supports both OAuth 1.0a and OAuth 2.0:

| | OAuth 1.0a | OAuth 2.0 |

|

| Flow | Three-legged (request token → authorize → access token) | Password grant (direct token exchange) | | Credentials | Consumer key/secret + token/secret pair | Client ID/secret + Bearer access token | | API path | /json/{function} or /xml/{function} | /oauth2/{function} | | Signing | Request signing required | Bearer token in header |

OAuth 2.0 is simpler to integrate for server-side applications where the user trusts your application with their Telldus Live! credentials. OAuth 1.0a remains available for applications that require a browser-based authorization flow without handling the user's password.

## Security Considerations

• Protect client credentials: Never expose your Client Secret in client-side code or public repositories.
• Use HTTPS: Always communicate with the Telldus API over HTTPS in production.
• Store tokens securely: Access and refresh tokens grant access to the user's Telldus account. Store them encrypted and never log them in plain text.
• Prefer refresh tokens: Cache the refresh token and use it to obtain new access tokens instead of repeatedly sending the user's password.