Welcome to aiodukeenergy documentation!¶

Installation & Usage

Project Info

aiodukeenergy¶

Documentation: https://aiodukeenergy.readthedocs.io

Source Code: https://github.com/hunterjm/aiodukeenergy

Asyncio Duke Energy

Installation¶

Install this via pip (or your favourite package manager):

pip install aiodukeenergy

Usage¶

Duke Energy uses Auth0 with CAPTCHA protection which blocks automated logins. Authentication requires a browser-based OAuth flow using a Chrome extension to capture the mobile app’s custom redirect URL.

Setup¶

Install the Chrome extension:
- Download the latest chrome-extension.zip from releases (or use ./chrome-extension/ from source)
- Extract the zip file
- Open Chrome and navigate to chrome://extensions/
- Enable “Developer mode”
- Click “Load unpacked” and select the extracted folder
Run the browser authentication script:
```
cd examples
python browser_auth.py
```
The script will:
- Open your browser to Duke Energy’s login page
- After you log in, the extension captures the authorization code
- Exchange the code for API tokens
- Save tokens to duke_tokens.json

Using Tokens¶

Once you have tokens, use them with the library:

import asyncio
import aiohttp
from aiodukeenergy import Auth0Client, DukeEnergy, DukeEnergyAuth


async def main():
    # Option 1: Load from token file
    import json

    with open("duke_tokens.json") as f:
        tokens = json.load(f)

    async with aiohttp.ClientSession() as session:
        auth0_client = Auth0Client(session)
        auth = DukeEnergyAuth(
            session,
            auth0_client,
            access_token=tokens["access_token"],
            refresh_token=tokens.get("refresh_token"),
            id_token=tokens.get("id_token"),
        )

        client = DukeEnergy(auth)

        accounts = await client.get_accounts()
        print(accounts)

        meters = await client.get_meters()
        for serial, meter in meters.items():
            print(f"Meter: {serial} ({meter['serviceType']})")


asyncio.run(main())

Browser OAuth Flow (Programmatic)¶

You can also integrate the OAuth flow into your own application:

import asyncio
import webbrowser
import aiohttp
from aiodukeenergy import Auth0Client, DukeEnergy, DukeEnergyAuth


async def main():
    async with aiohttp.ClientSession() as session:
        auth0_client = Auth0Client(session)
        auth = DukeEnergyAuth(session, auth0_client)

        # Step 1: Get authorization URL with PKCE
        auth_url, state, code_verifier = auth0_client.get_authorization_url()

        # Step 2: Open browser for user login
        webbrowser.open(auth_url)

        # Step 3: Get the authorization code (captured by Chrome extension)
        code = input("Enter the authorization code: ")

        # Step 4: Exchange code for tokens
        await auth.authenticate_with_code(code, code_verifier)

        # Now you can make API calls
        client = DukeEnergy(auth)
        accounts = await client.get_accounts()
        print(accounts)


asyncio.run(main())

Available Classes¶

Auth0Client - OAuth2/OIDC client for Duke Energy’s Auth0
- get_authorization_url() - Generate browser OAuth URL with PKCE (returns url, state, code_verifier)
- exchange_code(code, code_verifier) - Exchange authorization code for tokens
- refresh_token(refresh_token) - Refresh expired tokens
AbstractDukeEnergyAuth - Abstract base class for auth providers
- async_get_id_token() - Get a valid ID token (abstract)
- async_get_access_token() - Get a valid access token
- request(method, url, **kwargs) - Make authenticated requests
DukeEnergyAuth - Concrete auth implementation using Auth0Client
- authenticate_with_code(code, code_verifier) - Complete OAuth flow
- token - Property to get current token dictionary
DukeEnergy - API client for Duke Energy
- get_accounts() - Get all accounts
- get_meters() - Get all meters
- get_energy_usage(meter_serial, interval, view, start_date, end_date) - Get usage data

Contributors ✨¶

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!

Credits¶

This package was created with Copier and the browniebroke/pypackage-template project template.