PA-API OAuth2 Python Example

The following is an example of accessing the Telldus PA-API using Python and OAuth 2.0.

This example requires the following 3rd party Python packages: Flask, requests

You can install them using pip:

pip install -U flask requests

The Example Project

Running the Project

You can run the project's main application using Python from the root of the project folder:

python app.py

Then open your browser at http://127.0.0.1:5000.

### Project Directory

You can organise your project directory as follows:

telldus_oauth2_flask_app/
│
├── app.py
├── config.py
├── requirements.txt
└── templates/
    └── index.html

App & Configurations

Configuration

We define some commonly used constants here.

config.py

# config.py
import os

# 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
USERNAME = 'your@email.com'
PASSWORD = 'your_password'

# 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'

# Flask secret key for session management
SECRET_KEY = os.urandom(24)

# User-Agent sent with all API requests
USER_AGENT = 'MyTelldusApp/1.0'

requirements.txt

Flask
requests

The Flask Application

The main application.

app.py

# app.py

from flask import Flask, session, redirect, url_for, request, render_template, flash
import requests
import config
import json

app = Flask(__name__)
app.config.from_object('config')

# ---------------------------------------------------------------------------
# OAuth2 helpers
# ---------------------------------------------------------------------------

def obtain_tokens(username, password):
    """Obtain OAuth2 access and refresh tokens using the password grant."""
    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': config.USER_AGENT
    }
    response = requests.post(config.TOKEN_URL, data=payload, headers=headers)
    response.raise_for_status()
    data = response.json()
    access_token = data.get('access_token')
    refresh_token = data.get('refresh_token')
    if not access_token:
        raise ValueError(data.get('error_description', 'Failed to obtain access token.'))
    return access_token, refresh_token


def refresh_tokens(refresh_token):
    """Obtain a new access token using a 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': config.USER_AGENT
    }
    response = requests.post(config.TOKEN_URL, data=payload, headers=headers)
    response.raise_for_status()
    data = response.json()
    return data.get('access_token'), data.get('refresh_token')


def api_get(path, access_token, params=None):
    """Perform an authenticated GET request to the Telldus OAuth2 API."""
    headers = {
        'Authorization': f'Bearer {access_token}',
        'User-Agent': config.USER_AGENT
    }
    url = f'{config.API_BASE_URL}/{path}'
    response = requests.get(url, headers=headers, params=params or {})
    response.raise_for_status()
    return response.json()


def print_debug_message(message):
    print(f'[DEBUG] {message}')


# ---------------------------------------------------------------------------
# Routes
# ---------------------------------------------------------------------------

@app.route('/')
def index():
    access_token = session.get('access_token')
    print_debug_message('Accessing home page.')

    if not access_token:
        print_debug_message('No access token found. User not authenticated.')
        return render_template('index.html', authenticated=False)

    # Example API call: list devices
    params = {
        'supportedMethods': 65535,
        'format': 'json'
    }
    print_debug_message(f'Making API call to {config.API_BASE_URL}/devices/list')

    try:
        result = api_get('devices/list', access_token, params)
        devices = result.get('device', [])
        print_debug_message(f'Devices fetched: {json.dumps(devices, indent=2)}')
    except Exception as e:
        flash('An error occurred while fetching devices.', 'danger')
        print_debug_message(f'Exception during API call: {str(e)}')
        devices = []

    return render_template('index.html',
                           authenticated=True,
                           devices=devices,
                           access_token=access_token)


@app.route('/login', methods=['GET', 'POST'])
def login():
    if request.method == 'POST':
        username = request.form.get('username', '').strip()
        password = request.form.get('password', '').strip()

        if not username or not password:
            flash('Username and password are required.', 'warning')
            return redirect(url_for('login'))

        print_debug_message(f'Attempting OAuth2 login for user: {username}')
        try:
            access_token, refresh_token = obtain_tokens(username, password)
            print_debug_message('OAuth2 tokens obtained successfully.')
        except Exception as e:
            flash(f'Login failed: {e}', 'danger')
            print_debug_message(f'Login failed: {e}')
            return redirect(url_for('login'))

        session['access_token'] = access_token
        session['refresh_token'] = refresh_token
        flash('You have successfully logged in.', 'success')
        return redirect(url_for('index'))

    return render_template('index.html', authenticated=False, show_login_form=True)


@app.route('/logout')
def logout():
    print_debug_message('Logging out user.')
    session.clear()
    flash('You have been logged out.', 'success')
    return redirect(url_for('index'))


@app.route('/devices')
def devices():
    access_token = session.get('access_token')
    print_debug_message('Accessing devices route.')

    if not access_token:
        flash('You need to log in first.', 'warning')
        return redirect(url_for('index'))

    params = {'supportedMethods': 65535, 'format': 'json'}
    try:
        result = api_get('devices/list', access_token, params)
        devices = result.get('device', [])
    except Exception as e:
        flash('Failed to fetch devices.', 'danger')
        print_debug_message(f'Exception: {e}')
        devices = []

    return render_template('index.html',
                           authenticated=True,
                           devices=devices,
                           show_devices=True)


@app.route('/clients')
def clients():
    access_token = session.get('access_token')
    print_debug_message('Accessing clients route.')

    if not access_token:
        flash('You need to log in first.', 'warning')
        return redirect(url_for('index'))

    params = {'format': 'json'}
    try:
        result = api_get('clients/list', access_token, params)
        clients = result.get('client', [])
    except Exception as e:
        flash('Failed to fetch clients.', 'danger')
        print_debug_message(f'Exception: {e}')
        clients = []

    return render_template('index.html',
                           authenticated=True,
                           clients=clients,
                           show_clients=True)


if __name__ == '__main__':
    app.secret_key = config.SECRET_KEY
    app.run(debug=True)

The HTML Template

The home page also serves as the login form and results view.

templates/index.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Telldus OAuth2 Flask App</title>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css">
</head>
<body>
<div class="container mt-5">

    {% with messages = get_flashed_messages(with_categories=true) %}
      {% if messages %}
        {% for category, message in messages %}
          <div class="alert alert-{{ category }} alert-dismissible fade show" role="alert">
            {{ message }}
            <button type="button" class="btn-close" data-bs-dismiss="alert" aria-label="Close"></button>
          </div>
        {% endfor %}
      {% endif %}
    {% endwith %}

    <h1 class="mb-4">Telldus Live! OAuth2 Integration</h1>

    {% if not authenticated %}

        {% if show_login_form %}
            <p>Enter your Telldus Live! credentials to connect.</p>
            <form method="POST" action="{{ url_for('login') }}">
                <div class="mb-3">
                    <label for="username" class="form-label">Username (email)</label>
                    <input type="email" class="form-control" id="username" name="username" required>
                </div>
                <div class="mb-3">
                    <label for="password" class="form-label">Password</label>
                    <input type="password" class="form-control" id="password" name="password" required>
                </div>
                <button type="submit" class="btn btn-primary">Connect with Telldus</button>
            </form>
        {% else %}
            <p>You are not connected to Telldus Live!.</p>
            <a href="{{ url_for('login') }}" class="btn btn-primary">Connect with Telldus</a>
        {% endif %}

    {% else %}
        <p>You are connected to Telldus Live!</p>
        <a href="{{ url_for('logout') }}" class="btn btn-danger">Logout</a>

        <hr>

        {% if show_devices or devices is defined %}
            <h2>Devices</h2>
            {% if devices %}
                <ul class="list-group">
                    {% for device in devices %}
                        <li class="list-group-item">
                            <strong>{{ device.name }}</strong> (ID: {{ device.id }})
                        </li>
                    {% endfor %}
                </ul>
            {% else %}
                <p>No devices found.</p>
            {% endif %}
        {% endif %}

        {% if show_clients and clients is defined %}
            <h2>Clients</h2>
            {% if clients %}
                <ul class="list-group">
                    {% for client in clients %}
                        <li class="list-group-item">
                            <strong>{{ client.name }}</strong> (ID: {{ client.id }})
                        </li>
                    {% endfor %}
                </ul>
            {% else %}
                <p>No clients found.</p>
            {% endif %}
        {% endif %}

        {% if not show_devices and not show_clients %}
            <h2>Quick Links</h2>
            <a href="{{ url_for('devices') }}" class="btn btn-info me-2">View Devices</a>
            <a href="{{ url_for('clients') }}" class="btn btn-info">View Clients</a>
        {% endif %}

    {% endif %}
</div>

<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js"></script>
</body>
</html>

Command-Line Alternative

If you only need to obtain tokens without a web interface, you can use a standalone script. The repository includes oauth2.py for this purpose.

Create a config.ini file:

[oauth2]
client_id = Your client ID
client_secret = Your client secret
username = your@email.com
password = your_password

[server]
user_agent = MyTelldusApp/1.0

Run the script:

python oauth2.py

On success, the access token and refresh token are printed to the console.

Testing an API Call from the Command Line

Once you have an access token, you can test an API call directly with curl:

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

Replace YOUR_ACCESS_TOKEN with the token obtained from the login flow or the command-line script.