Clerk Python SDK

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.

Install

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

Imports

• Clerk

  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

  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