Stytch Python Client

14.4.0 · active · verified Wed Apr 15

The Stytch Python library provides an interface to the Stytch user infrastructure API, simplifying the integration of authentication and authorization flows into Python applications. It supports various authentication methods like Email Magic Links, OAuth, SMS/WhatsApp passcodes, and more for both B2C and B2B use cases. The library is actively maintained with frequent releases, often multiple times a month for minor versions, indicating an agile development cycle.

Warnings

breaking Starting with Python SDK v6, asynchronous support was added. All API methods now have synchronous and asynchronous equivalents (e.g., `client.magic_links.authenticate` vs. `client.magic_links.authenticate_async`). Ensure you use the correct method based on your application's concurrency model.
Fix: For async applications, append `_async` to method calls (e.g., `await client.users.get_async(...)`). For sync applications, use the methods without `_async`.
gotcha All structured errors returned from the Stytch API are encapsulated in `stytch.StytchError` exceptions. Generic exception catching might mask specific API error details.
Fix: Always catch `stytch.StytchError` to properly handle and inspect API-specific error details via the `.details` property.
gotcha Stytch differentiates between Consumer (B2C) and B2B authentication. You must use the appropriate client (`stytch.Client` for B2C or `stytch.B2BClient` for B2B) as their API interfaces and expected payloads differ significantly.
Fix: Instantiate `stytch.Client` for Consumer projects and `stytch.B2BClient` for B2B projects. Do not mix their usage, as B2B specific endpoints will not be available on `stytch.Client` and vice-versa.
gotcha For Machine-to-Machine (M2M) authentication endpoints, such as `POST /oauth2/token`, authentication is performed using `client_id` and `client_secret` rather than the standard `project_id` and `secret` used for other API calls.
Fix: When interacting with M2M token endpoints, ensure you provide the M2M `client_id` and `client_secret` for authentication, either in the request body or via HTTP Basic Auth.
gotcha When migrating sessions from an existing authentication system using `sessions.migrate_async`, the API is designed to return a full-fledged Stytch session. If your existing system handles Multi-Factor Authentication (MFA) prior to migration, that MFA logic typically needs to remain outside the Stytch ecosystem for the `migrate` call.
Fix: If MFA is handled by your legacy system before session migration, complete the MFA flow in your existing system, then call Stytch's `sessions.migrate` (or `migrate_async`) to establish the final Stytch session.

Install

pip install stytch Install Stytch Python client

Imports

Client

import stytch
client = stytch.Client(...)

Used for B2C authentication flows.

B2BClient
```
import stytch
b2b_client = stytch.B2BClient(...)
```
Used for B2B authentication flows, requires different API calls specific to organizations and members.
StytchError
```
from stytch import StytchError
```
The base exception for all structured errors from the Stytch API.

Quickstart

This quickstart demonstrates how to initialize the Stytch client using environment variables and send a magic link for user login or signup. It includes basic error handling for `StytchError` exceptions.

import os
import stytch

# Initialize the Stytch client using environment variables
# Replace with your actual project_id and secret, or set as environment variables
# For B2C authentication:
client = stytch.Client(
    project_id=os.environ.get("STYTCH_PROJECT_ID", "project-test-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"),
    secret=os.environ.get("STYTCH_SECRET", "secret-test-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"),
    # Optionally specify a custom base URL for all API calls
    # custom_base_url="https://api.custom-domain.com/",
)

# For B2B authentication, use stytch.B2BClient instead:
# b2b_client = stytch.B2BClient(
#     project_id=os.environ.get("STYTCH_PROJECT_ID", "project-test-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"),
#     secret=os.environ.get("STYTCH_SECRET", "secret-test-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"),
# )

try:
    # Example: Send a magic link for login or signup
    email_to_authenticate = "test@example.com"
    response = client.magic_links.email.login_or_create(
        email=email_to_authenticate,
        login_magic_link_url="http://localhost:3000/authenticate",
        signup_magic_link_url="http://localhost:3000/authenticate",
    )
    print(f"Magic link sent to {email_to_authenticate}. Status code: {response.status_code}")
    print(f"Request ID: {response.request_id}")
except stytch.StytchError as e:
    print(f"Stytch API error occurred: {e.details}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

view raw JSON →