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

Timestamp:

Aug 12, 2026, 11:53:56 AM (8 days ago)

Author:

edwin

Comment:

Draft

Guides/Telldus Live API OAuth2

@@ +1 @@
+
+== 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 [https://pa-api.telldus.com/keys/showToken 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.