Skip to main content

aiodukeenergy-co

CI Status Test coverage percentage

Poetry Ruff pre-commit

PyPI Version Supported Python versions License


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


Asyncio Duke Energy

Crash Override Edition

I wanted a pip available fork that I could more actively maintain and add api calls to without waiting on pull requests. Includes fixes for gas usage, support for MONTHLY usage requests, and billing and payment information api calls.

Installation

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

pip install aiodukeenergy-co

Import as aiodukeenergy_co

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

  1. Add the appropriate extension for your browser:

    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

    safari-extension

    Requires XCode and a free developer account

    • Download the latest safari-extension.zip from releases (or use ./safari-extension/ from source)
    • Extract the zip file
    • Open the Xcode project
    • Go to project settings and set your free developer account as the 'Team' for both Targets (com.local.duke-energy-oauth-helper and com.local.duke-energy-oauth-helper.Extension). Also ensure 'Signing Certificate' is set to 'Development'
    • Quit Safari if open and build the extension
    • Open Safai and enable the extension in Safari settings
    • Build the extension again
    • Enable access to all URLs or a specific URL (https://login.duke-energy.com) in the extension settings
  2. Run the browser authentication script:

    cd examples
    python browser_auth.py
    
  3. 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_co 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_co 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
    • get_invoices(account_number) - Get the account's invoice list (most recent first)
    • get_billing_payment_info(include_closed=True) - Get billing/payment info per account (balance, dueDate, abbreviatedBillStatus, ...)
    • get_monthly_usage(meter_serial, period, start_date) - Get summarized usage/bill comparison (this period, last period, same period last year). For BILLINGCYCLE, pass start_date = latest invoice billEndDate + 1 day (derive once via get_invoices and reuse across meters on the account)

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.

Metadata

Release files for aiodukeenergy-co 1.3.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aiodukeenergy-co 1.3.1
File Size Uploaded Provenance Actions
aiodukeenergy_co-1.3.1.tar.gz 18.4 kB With provenance Details for aiodukeenergy_co-1.3.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aiodukeenergy-co 1.3.1
File Interpreter ABI Platform Actions
aiodukeenergy_co-1.3.1-py3-none-any.whl Python 3 none any Details for aiodukeenergy_co-1.3.1-py3-none-any.whl

Total release size: 36.7 kB

Release files / aiodukeenergy_co-1.3.1.tar.gz

Download URL aiodukeenergy_co-1.3.1.tar.gz
Size 18.4 kB
Tags Source
SHA-256 checksum
How to use checksums
689947fcefc7c46d30a219c57a2926dcf1076b9ab0ea3006434f0dca1e165903
BLAKE2b-256 checksum
How to use checksums
4eea0b34edef4fcfd3f7a30ca3d684f95c1108d01c7a2c7961d526a791a8ade9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Release files / aiodukeenergy_co-1.3.1-py3-none-any.whl

Download URL aiodukeenergy_co-1.3.1-py3-none-any.whl
Size 18.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a04e91cbf70037072a2617be185d46a394469e987ac0e0d7bbd31443657230ac
BLAKE2b-256 checksum
How to use checksums
37e4461ef439485072a56d7efdd0003c487fd6464fb872cfaf3e29ccf454e554
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Security for aiodukeenergy-co 1.3.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for aiodukeenergy_co-1.3.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page