feat(auth): support Bearer token alongside X-API-Key

Add an optional ``auth_method`` keyword on the ``SharpAPI`` and
``AsyncSharpAPI`` constructors. Defaults to ``"x-api-key"`` (existing
behaviour — fully back-compat; no caller changes required). When set to
``"bearer"`` the SDK sends ``Authorization: Bearer <key>`` instead of
the ``X-API-Key`` header, matching the Go server's three accepted REST
auth modes (header, Bearer, query).

Why: customers running behind IAM layers, SSO gateways, or corporate
proxies often have non-standard headers stripped or rewritten. Standard
``Authorization: Bearer`` survives those hops and integrates cleanly
with off-the-shelf auth middleware.

SSE streams are intentionally unchanged — they always authenticate via
the ``?api_key=`` query param because the EventSource spec does not
allow custom request headers.

Bumps version 0.2.4 -> 0.2.5 (new public API surface). Adds 2 tests
(sync + async) verifying the Bearer header is sent and X-API-Key is
omitted in bearer mode.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Mlaz-code

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sharpapi"
-version = "0.2.4"
+version = "0.2.5"
 description = "Official Python SDK for the SharpAPI real-time sports betting odds API"
 readme = "README.md"
 license = "MIT"

src/sharpapi/__init__.py

@@ -57,7 +57,7 @@
 )
 from .streaming import EventStream
 
-__version__ = "0.2.4"
+__version__ = "0.2.5"
 
 __all__ = [
     # Clients

src/sharpapi/_base.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import random
+from typing import Literal
 
 import httpx
 
@@ -19,7 +20,12 @@
 
 DEFAULT_BASE_URL = "https://api.sharpapi.io"
 DEFAULT_TIMEOUT = 30.0
-USER_AGENT = "sharpapi-python/0.2.4"
+USER_AGENT = "sharpapi-python/0.2.5"
+
+# Supported REST authentication methods. SSE always uses ``?api_key=`` query
+# regardless of this setting because EventSource cannot set custom headers.
+AuthMethod = Literal["x-api-key", "bearer"]
+DEFAULT_AUTH_METHOD: AuthMethod = "x-api-key"
 
 RETRY_STATUSES = frozenset({502, 503, 504})
 RETRY_MAX_ATTEMPTS = 3
@@ -138,13 +144,28 @@ def handle_errors(response: httpx.Response) -> None:
         raise SharpAPIError(error_msg, code=code, status=status)
 
 
-def make_headers(api_key: str) -> dict[str, str]:
-    """Build default request headers."""
-    return {
-        "X-API-Key": api_key,
+def make_headers(
+    api_key: str,
+    auth_method: AuthMethod = DEFAULT_AUTH_METHOD,
+) -> dict[str, str]:
+    """Build default request headers.
+
+    Args:
+        api_key: The SharpAPI key (e.g. ``sk_live_...``).
+        auth_method: Either ``"x-api-key"`` (default — sends an
+            ``X-API-Key`` header) or ``"bearer"`` (sends
+            ``Authorization: Bearer <key>``). Useful when proxies, IAM
+            layers, or SSO gateways strip non-standard custom headers.
+    """
+    headers: dict[str, str] = {
         "Content-Type": "application/json",
         "User-Agent": USER_AGENT,
     }
+    if auth_method == "bearer":
+        headers["Authorization"] = f"Bearer {api_key}"
+    else:
+        headers["X-API-Key"] = api_key
+    return headers
 
 
 def _int_or_none(value: str | None) -> int | None:

src/sharpapi/async_client.py

@@ -8,9 +8,11 @@
 import httpx
 
 from ._base import (
+    DEFAULT_AUTH_METHOD,
     DEFAULT_BASE_URL,
     DEFAULT_TIMEOUT,
     RETRY_MAX_ATTEMPTS,
+    AuthMethod,
     handle_errors,
     make_headers,
     parse_rate_limit,
@@ -44,6 +46,17 @@ class AsyncSharpAPI:
     Provides typed access to odds, +EV, arbitrage, middles, and streaming
     endpoints using ``async``/``await``.
 
+    Args:
+        api_key: Your SharpAPI key (e.g. ``sk_live_...``).
+        base_url: Override the API base URL (defaults to production).
+        timeout: HTTP timeout in seconds.
+        auth_method: How to send the API key on REST requests. ``"x-api-key"``
+            (default) sends the ``X-API-Key`` header. ``"bearer"`` sends
+            ``Authorization: Bearer <key>`` instead — useful when running
+            behind IAM layers, SSO, or API gateways that strip custom
+            headers. SSE streams (sync client only) always authenticate via
+            ``?api_key=`` query and are unaffected.
+
     Example::
 
         import asyncio
@@ -55,6 +68,10 @@ async def main():
                 for arb in arbs.data:
                     print(f"{arb.profit_percent}% — {arb.event_name}")
 
+            # Or, behind a proxy that requires standard Bearer auth:
+            async with AsyncSharpAPI("sk_live_xxx", auth_method="bearer") as c:
+                ...
+
         asyncio.run(main())
     """
 
@@ -64,16 +81,18 @@ def __init__(
         *,
         base_url: str = DEFAULT_BASE_URL,
         timeout: float = DEFAULT_TIMEOUT,
+        auth_method: AuthMethod = DEFAULT_AUTH_METHOD,
     ):
         if not api_key:
             raise ValueError("api_key is required")
 
         self._api_key = api_key
+        self._auth_method: AuthMethod = auth_method
         self._base_url = base_url.rstrip("/")
         self._timeout = timeout
         self._http = httpx.AsyncClient(
             base_url=f"{self._base_url}/api/v1",
-            headers=make_headers(api_key),
+            headers=make_headers(api_key, auth_method),
             timeout=timeout,
         )
         self._last_rate_limit = RateLimitInfo()

src/sharpapi/client.py

@@ -8,9 +8,11 @@
 import httpx
 
 from ._base import (
+    DEFAULT_AUTH_METHOD,
     DEFAULT_BASE_URL,
     DEFAULT_TIMEOUT,
     RETRY_MAX_ATTEMPTS,
+    AuthMethod,
     handle_errors,
     make_headers,
     parse_rate_limit,
@@ -45,12 +47,26 @@ class SharpAPI:
     Provides typed access to odds, +EV, arbitrage, middles, and streaming
     endpoints.
 
+    Args:
+        api_key: Your SharpAPI key (e.g. ``sk_live_...``).
+        base_url: Override the API base URL (defaults to production).
+        timeout: HTTP timeout in seconds.
+        auth_method: How to send the API key on REST requests. ``"x-api-key"``
+            (default) sends the ``X-API-Key`` header. ``"bearer"`` sends
+            ``Authorization: Bearer <key>`` instead — useful when running
+            behind IAM layers, SSO, or API gateways that strip custom
+            headers. SSE streams always authenticate via ``?api_key=`` query
+            (EventSource cannot set headers) and are unaffected.
+
     Example::
 
         from sharpapi import SharpAPI
 
         client = SharpAPI("sk_live_xxx")
 
+        # Or, behind a proxy that requires standard Bearer auth:
+        client = SharpAPI("sk_live_xxx", auth_method="bearer")
+
         # Get arbitrage opportunities
         arbs = client.arbitrage.get(min_profit=1.0)
         for arb in arbs.data:
@@ -73,16 +89,18 @@ def __init__(
         *,
         base_url: str = DEFAULT_BASE_URL,
         timeout: float = DEFAULT_TIMEOUT,
+        auth_method: AuthMethod = DEFAULT_AUTH_METHOD,
     ):
         if not api_key:
             raise ValueError("api_key is required")
 
         self._api_key = api_key
+        self._auth_method: AuthMethod = auth_method
         self._base_url = base_url.rstrip("/")
         self._timeout = timeout
         self._http = httpx.Client(
             base_url=f"{self._base_url}/api/v1",
-            headers=make_headers(api_key),
+            headers=make_headers(api_key, auth_method),
             timeout=timeout,
         )
         self._last_rate_limit = RateLimitInfo()

tests/test_async_client.py

@@ -223,3 +223,16 @@ async def test_api_key_header_sent(self):
         async with AsyncSharpAPI(API_KEY) as client:
             await client.sports.list()
             assert route.calls[0].request.headers["x-api-key"] == API_KEY
+            assert "authorization" not in route.calls[0].request.headers
+
+    @pytest.mark.asyncio
+    @respx.mock
+    async def test_bearer_auth_method_sends_authorization(self):
+        route = respx.get(f"{BASE_URL}/api/v1/sports").mock(
+            return_value=Response(200, json=SPORTS_RESPONSE)
+        )
+        async with AsyncSharpAPI(API_KEY, auth_method="bearer") as client:
+            await client.sports.list()
+            req = route.calls[0].request
+            assert req.headers["authorization"] == f"Bearer {API_KEY}"
+            assert "x-api-key" not in req.headers

tests/test_client.py

@@ -382,6 +382,20 @@ def test_api_key_header_sent(self):
         with SharpAPI(API_KEY) as client:
             client.sports.list()
             assert route.calls[0].request.headers["x-api-key"] == API_KEY
+            # Bearer must NOT be sent in the default mode.
+            assert "authorization" not in route.calls[0].request.headers
+
+    @respx.mock
+    def test_bearer_auth_method_sends_authorization(self):
+        route = respx.get(f"{BASE_URL}/api/v1/sports").mock(
+            return_value=Response(200, json=SPORTS_RESPONSE)
+        )
+        with SharpAPI(API_KEY, auth_method="bearer") as client:
+            client.sports.list()
+            req = route.calls[0].request
+            assert req.headers["authorization"] == f"Bearer {API_KEY}"
+            # X-API-Key must NOT be sent in bearer mode.
+            assert "x-api-key" not in req.headers
 
     @respx.mock
     def test_user_agent_sent(self):