Skip to content

feat(auth): add auth=False for self-hosted servers without authentication - #833

Open
GregHolmes wants to merge 1 commit into
mainfrom
feat/self-hosted-no-auth
Open

GregHolmes wants to merge 1 commit into
mainfrom
feat/self-hosted-no-auth

Conversation

@GregHolmes

Copy link
Copy Markdown
Contributor

Proposed changes

Self-hosted and local Deepgram servers can run without request authentication. The Python client can't connect to one without inventing a key: constructing DeepgramClient or AsyncDeepgramClient with no api_key and no DEEPGRAM_API_KEY raises:

The client must be instantiated by either passing in api_key or setting DEEPGRAM_API_KEY

This adds auth=False, matching the JavaScript SDK's auth: false:

client = DeepgramClient(
    environment=DeepgramClientEnvironment(
        base="http://127.0.0.1:8000",
        production="ws://127.0.0.1:8000",
        agent="ws://127.0.0.1:8000",
        agent_rest="http://127.0.0.1:8000",
    ),
    auth=False,
)
  • No key is required and DEEPGRAM_API_KEY is ignored.
  • No Authorization header is sent on HTTP requests or WebSocket handshakes. It is removed with the same client_wrapper.get_headers override that access_token already uses for Bearer auth, so every HTTP, async and WebSocket path is covered.
  • auth=False can't be combined with api_key or access_token (ValueError), and auth only accepts False.
  • When no key is available and the environment's base is not deepgram.com or *.deepgram.com, the missing-key error ends with a hint to pass auth=False. For Deepgram's hosted API the message is unchanged, apart from fixing the generated "instantiated be either" wording: the custom client now raises the missing-key error itself in both cases, as it already did for an explicit api_key=None.

All changes are in src/deepgram/client.py (already frozen in .fernignore). The credential handling shared by the sync and async clients moved into a _resolve_credentials helper, with the existing access_token, explicit-None and DEEPGRAM_API_KEY re-read behaviour kept as before.

The README gains a "Self-Hosted and Local Servers Without Authentication" section under Authentication.

Types of changes

  • Bugfix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Documentation update or tests (if none of the other choices apply)

Checklist

  • I have read the CONTRIBUTING doc
  • Lint and unit tests pass locally with my changes
  • I have added tests that prove my fix is effective or that my feature works
  • I have added necessary documentation (if appropriate)

Further comments

tests/custom/test_self_hosted_no_auth.py (added to .fernignore), 18 tests:

  • Construction without a key (sync and async), and DEEPGRAM_API_KEY ignored under auth=False.
  • No Authorization header over HTTP (sync and async, via httpx.MockTransport) and on the Listen v2 WebSocket handshake (sync and async).
  • ValueError when combined with api_key or access_token, and for values other than False.
  • The hint for a loopback environment, an explicit api_key=None, the async client, and a look-alike host (notdeepgram.com); the unchanged message for the default environment and api.eu.deepgram.com.
  • An explicit api_key is still sent to a self-hosted environment.

17 of the 18 fail without the change. tests/custom and tests/utils pass (1,132 tests) apart from two existing failures in test_core_utilities_coverage.py that only occur on Windows (pathlib.Path("/x") encodes as \x) and fail the same way on main. ruff check, ruff format --check and mypy are clean.

🤖 Generated with Claude Code

…tion

Self-hosted and local Deepgram servers can run without request
authentication, but the client could not be constructed without an API
key, so there was no way to connect without inventing one.

DeepgramClient and AsyncDeepgramClient now accept auth=False: no key is
required, DEEPGRAM_API_KEY is ignored, and no Authorization header is
sent on HTTP requests or WebSocket handshakes. It cannot be combined with
api_key or access_token.

When no key is available and the environment is not a Deepgram host, the
missing-key error now suggests auth=False. The message for Deepgram's
hosted API is unchanged apart from fixing "instantiated be either".

Also documents the self-hosted setup in the README.
@github-actions

Copy link
Copy Markdown
Contributor

Code Coverage

Package Line Rate Branch Rate Complexity Health
src.deepgram 96% 91% 0 ✔
src.deepgram.agent 100% 100% 0 ✔
src.deepgram.agent.v1 98% 100% 0 ✔
src.deepgram.agent.v1.settings 100% 100% 0 ✔
src.deepgram.agent.v1.settings.think 100% 100% 0 ✔
src.deepgram.agent.v1.settings.think.models 97% 100% 0 ✔
src.deepgram.auth 100% 100% 0 ✔
src.deepgram.auth.v1 100% 100% 0 ✔
src.deepgram.auth.v1.tokens 97% 100% 0 ✔
src.deepgram.core 89% 84% 0 ➖
src.deepgram.errors 100% 100% 0 ✔
src.deepgram.helpers 98% 92% 0 ✔
src.deepgram.listen 100% 100% 0 ✔
src.deepgram.listen.v1 98% 93% 0 ✔
src.deepgram.listen.v1.media 97% 100% 0 ✔
src.deepgram.listen.v2 98% 93% 0 ✔
src.deepgram.manage 100% 100% 0 ✔
src.deepgram.manage.v1 100% 100% 0 ✔
src.deepgram.manage.v1.models 96% 100% 0 ✔
src.deepgram.manage.v1.projects 97% 100% 0 ✔
src.deepgram.manage.v1.projects.billing 100% 100% 0 ✔
src.deepgram.manage.v1.projects.billing.balances 96% 100% 0 ✔
src.deepgram.manage.v1.projects.billing.breakdown 97% 100% 0 ✔
src.deepgram.manage.v1.projects.billing.fields 97% 100% 0 ✔
src.deepgram.manage.v1.projects.billing.purchases 97% 100% 0 ✔
src.deepgram.manage.v1.projects.keys 96% 100% 0 ✔
src.deepgram.manage.v1.projects.members 97% 100% 0 ✔
src.deepgram.manage.v1.projects.members.invites 96% 100% 0 ✔
src.deepgram.manage.v1.projects.members.scopes 96% 100% 0 ✔
src.deepgram.manage.v1.projects.models 96% 100% 0 ✔
src.deepgram.manage.v1.projects.usage 98% 100% 0 ✔
src.deepgram.manage.v1.projects.usage.breakdown 97% 100% 0 ✔
src.deepgram.manage.v1.projects.usage.fields 97% 100% 0 ✔
src.deepgram.read 100% 100% 0 ✔
src.deepgram.read.v1 100% 100% 0 ✔
src.deepgram.read.v1.text 98% 100% 0 ✔
src.deepgram.self_hosted 100% 100% 0 ✔
src.deepgram.self_hosted.v1 100% 100% 0 ✔
src.deepgram.self_hosted.v1.distribution_credentials 96% 100% 0 ✔
src.deepgram.speak 100% 100% 0 ✔
src.deepgram.speak.v1 98% 97% 0 ✔
src.deepgram.speak.v1.audio 91% 80% 0 ✔
src.deepgram.speak.v2 98% 93% 0 ✔
src.deepgram.speak.v2.audio 100% 100% 0 ✔
src.deepgram.voice_agent 100% 100% 0 ✔
src.deepgram.voice_agent.configurations 95% 100% 0 ✔
src.deepgram.voice_agent.variables 95% 100% 0 ✔
Summary 96% (6653 / 6955) 92% (1465 / 1590) 0 ✔

Scope: hand-maintained SDK logic. Fern-generated data models (types/, requests/), package __init__.py files, version.py, and the unused core/http_sse/ scaffolding are excluded — see .coveragerc. Unscoped whole-package coverage is ~70%.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant