oura-toolkit (Python)

Python SDK for the Oura Ring API v2, part of oura-toolkit.

pip install oura-toolkit

One distribution, two submodules:

• oura_toolkit.api — the data-plane client, generated from Oura's own OpenAPI spec (do not hand-edit — regenerated by just gen-py). Auth-agnostic: bring a Bearer token.
• oura_toolkit.auth — hand-written OAuth companion: token store, refresh with rotation, spec-pinned OAuth metadata. It shares the oura CLI's on-disk token store (~/.config/oura-toolkit/ on Unix/macOS, %LOCALAPPDATA%\oura-toolkit\ on Windows) and its cross-process refresh protocol, so the CLI, its MCP server, and your Python code can all rotate the same tokens safely.

With a token you manage yourself:

from oura_toolkit.api import ApiClient, Configuration

config = Configuration(access_token="<your Oura access token>")
with ApiClient(config) as client:
    ...

Or let the companion keep the token fresh (run oura auth setup / oura auth login once — interactive OAuth deliberately lives in the CLI, never in this package):

from oura_toolkit.api import ApiClient
from oura_toolkit.auth import TokenManager

manager = TokenManager.load()  # reads the shared token store
with ApiClient(manager.configuration()) as client:
    ...  # every request carries a proactively refreshed Bearer token

On a 401, call manager.force_refresh() and retry the request once.

Oura uses OAuth2 with your own registered application (personal access tokens were deprecated in Dec 2025) — see the toolkit README for the registration walkthrough and the oura auth setup flow.