Clerk Python SDK

Common errors

• ModuleNotFoundError: No module named 'clerk' OR ModuleNotFoundError: No module named 'clerk_backend_api'

  cause The official 'clerk-backend-api' package is imported as 'clerk_backend_api', but developers might try to import 'clerk' due to older tutorials or package name confusion (e.g., from the 'clerk-sdk-python' package or alpha versions). Alternatively, 'clerk-backend-api' might not be installed at all.
  fix Ensure 'clerk-backend-api' is installed (pip install clerk-backend-api) and import it correctly as 'from clerk_backend_api import Clerk'.

• Error: Missing Clerk Secret Key OR Error: Clerk: Invalid API key

  cause The CLERK_SECRET_KEY environment variable is not set, is incorrect, or does not match the Clerk application it's being used with.
  fix Set CLERK_SECRET_KEY in your environment variables (e.g., in a .env file) to the Secret Key found in your Clerk Dashboard under API Keys.

• 401 Could not authenticate request. OR Invalid Authorization header format.

  cause The Authorization header in the request is missing, malformed, or contains an invalid or expired JWT/API key.
  fix Ensure your backend is receiving a valid Bearer token from the frontend and is correctly passing your Clerk Secret Key or a valid session token in the 'Authorization: Bearer <token>' header when making requests to the Clerk API or when authenticating incoming requests.

• request_body_invalid (often seen when using expires_in_seconds with create_session_token)

  cause When calling 'create_session_token', the 'expires_in_seconds' argument is being passed as a float, but the Clerk API expects an integer value.
  fix Cast the 'expires_in_seconds' argument to an integer before passing it to the 'create_session_token' method. Example: 'expires_in_seconds=int(some_float_value)'.

• AttributeError: 'Clerk' object has no attribute 'users' (or similar for other resources like 'email_addresses', 'sessions')

  cause Attempting to access a sub-resource or method on the 'Clerk' client that either does not exist, is named differently, or is not available in the imported SDK version.
  fix Consult the official 'clerk-backend-api' documentation or the SDK source code to verify the correct attribute and method names for the desired API operation (e.g., 'clerk.users' vs 'clerk.users', 'list()' vs 'get_all()'). For example, to list users, use 'clerk.users.list()' or to get an email address, use 'clerk.email_addresses.get(email_address_id=...)'.

Warnings

• breaking 'pip install clerk-sdk' installs an unrelated third-party package (F-One's document management SDK, not Clerk auth). It has the same top-level Clerk class name but completely different API. Silent wrong-package installation.
  Fix: Always pip install clerk-backend-api (with dashes). Verify with: pip show clerk-backend-api
• breaking The official SDK was only released Oct 2024. All tutorials and LLM training data before that date use manual JWT verification with PyJWT + JWKS endpoint fetch — not the SDK. That pattern still works but is not the official approach.
  Fix: Use sdk.authenticate_request() from clerk_backend_api for request auth instead of manual jwt.decode().
• breaking SDK has had breaking changes between minor versions during beta/v4-v5 cycle. The docs warn: 'pin usage to a specific package version' to avoid silent breakage.
  Fix: Pin: clerk-backend-api==5.0.2 in requirements.txt. Review changelog before upgrading.
• breaking bearer_auth must be your Secret Key (sk_live_... or sk_test_...), NOT the Publishable Key (pk_live_... or pk_test_...). Passing a Publishable Key returns 401 with no clear error message.
  Fix: Clerk(bearer_auth=os.environ['CLERK_SECRET_KEY']). Secret key starts with sk_, not pk_.
• gotcha Clerk() must be used as a context manager (with Clerk(...) as clerk:) or explicitly closed to release HTTPX connection pool. Omitting causes ResourceWarning in long-lived processes.
  Fix: Use 'with Clerk(...) as clerk:' pattern. Or call clerk.close() explicitly.
• gotcha authenticate_request() requires an httpx.Request object, not a raw dict or string token. Framework-specific adapters are needed to convert Flask/Django/FastAPI request objects.
  Fix: For FastAPI: construct httpx.Request from request.headers and URL. Or use community packages like fastapi-clerk-auth for framework integration.
• gotcha Clerk API versioning: each SDK version pins to a specific API version. Upgrading the SDK may silently change API behavior (field renames, new required fields) not just the SDK interface.
  Fix: Pin SDK version in production. Review Clerk API changelog at clerk.com/changelog before upgrading.
• breaking The Clerk constructor expects the `CLERK_SECRET_KEY` environment variable to be set when accessing it via `os.environ['CLERK_SECRET_KEY']`. If this variable is not defined, a `KeyError` will occur, preventing the application from initializing.
  Fix: Ensure the `CLERK_SECRET_KEY` environment variable is set in your environment before running the application. For example, `export CLERK_SECRET_KEY="sk_live_..."` or configure it in your deployment environment.
• breaking The `CLERK_SECRET_KEY` environment variable must be set for the SDK to initialize. Accessing `os.environ['CLERK_SECRET_KEY']` when it's not set will raise a `KeyError`.
  Fix: Ensure `CLERK_SECRET_KEY` is set in the environment before running the application. For example, `export CLERK_SECRET_KEY=sk_test_...` or pass it via Docker/CI configurations.

Install

• pip install clerk-backend-api Python (official)

Imports

• Clerk
  wrong:

  from clerk import Clerk

  correct:

  from clerk_backend_api import Clerk

  Package is clerk-backend-api, imports as clerk_backend_api. 'from clerk import Clerk' raises ModuleNotFoundError. The 'clerk' PyPI package was an early alpha name that no longer receives updates.
• AuthenticateRequestOptions
  wrong:

  from clerk_backend_api import AuthenticateRequestOptions

  correct:

  from clerk_backend_api.jwks_helpers import AuthenticateRequestOptions

  JWT/request auth helpers are in the jwks_helpers submodule, not the top-level package.

Quickstart

Management API user listing and request authentication using clerk-backend-api v5.

import os
from clerk_backend_api import Clerk

# Management API — use CLERK_SECRET_KEY (sk_live_... or sk_test_...)
with Clerk(bearer_auth=os.environ['CLERK_SECRET_KEY']) as clerk:
    # List users
    users = clerk.users.list(limit=10)
    for user in users:
        print(user.email_addresses)

    # Get single user
    user = clerk.users.get(user_id='user_abc123')
    print(user.id)

# Request authentication (verify JWT from frontend)
import httpx
from clerk_backend_api.jwks_helpers import AuthenticateRequestOptions

def is_signed_in(request: httpx.Request) -> bool:
    sdk = Clerk(bearer_auth=os.environ['CLERK_SECRET_KEY'])
    state = sdk.authenticate_request(
        request,
        AuthenticateRequestOptions(
            authorized_parties=['https://your-app.com']
        )
    )
    return state.is_signed_in