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