Python SDK

authdog 0.1.1 is the official Python client for the Authdog REST API. Install it from PyPI. It is a management and userinfo client, not a web-framework session binding.

Need to protect FastAPI, Django, Flask, Starlette, or aiohttp routes? That is a different package. See Python backends.

Install

python -m pip install "authdog==0.1.1"

Requires Python 3.8.1+ and httpx 0.24+. Source: `python/` in authdog/sdk. PyPI: authdog.

Configure

Construct one client with the public API base URL. Pass a management Bearer credential (ad_…) when you call privileged endpoints:

import os
from authdog import AuthdogClient

client = AuthdogClient(
    "https://api.authdog.com",
    api_key=os.environ["AUTHDOG_API_TOKEN"],
)

Keep the token server-side. get_userinfo still uses the caller access token, not the management key.

Use the client as a context manager so the HTTP session closes:

from authdog import AuthdogClient

with AuthdogClient("https://api.authdog.com", api_key="ad_...") as client:
    probe = client.health()

health() is public and works without an API key.

Resolve a user from an access token

from authdog import APIError, AuthenticationError, AuthdogClient

client = AuthdogClient("https://api.authdog.com")

try:
    info = client.get_userinfo(access_token)
    print(info.user.display_name)
    print(info.user.emails[0].value)
except AuthenticationError:
    # 401: missing, invalid, or expired access token
    raise
except APIError:
    # transport or non-401 HTTP failure
    raise

UserInfoResponse uses snake_case attributes (user.display_name, session.remaining_seconds).

Call the management API

Namespaces wrap Waves 1–2 of the public /v1 surface:

with AuthdogClient("https://api.authdog.com", api_key="ad_...") as client:
    orgs = client.organizations.list()
    users = client.users.list("ten_123", "env_456", limit=25)

Directory calls take tenant_id then environment_id. OpenAPI at `/v1/openapi` is the field-level contract.

Errors

• AuthdogError — base class
• AuthenticationError — 401
• APIError — transport failure or other HTTP 4xx/5xx (status_code when present)

Next

• API reference: auth, versioning, and resource families
• Backend requests: validate sessions on incoming requests
• Python backends: FastAPI / Django / Flask / Starlette / aiohttp session bindings
• Users: directory model the users namespace talks to