Install & Compatibility
Where this runs
tested against v2.13.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.052s · 44MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.5s · import 0.964s · 44MB
43MB installed
● package 43MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DescopeClient
✓ from descope import DescopeClient
The primary class for interacting with the Descope API.
AuthException
✓ from descope import AuthException
Common exception for Descope authentication failures.
SESSION_TOKEN_NAME, REFRESH_SESSION_TOKEN_NAME
✓ from descope import SESSION_TOKEN_NAME, REFRESH_SESSION_TOKEN_NAME
Constants for session and refresh token names, often used with cookies or headers.
This quickstart demonstrates how to initialize the `DescopeClient` using a project ID and an optional management key (preferably from environment variables). It then shows a basic example of attempting to validate a session token. Remember to replace placeholder tokens with actual values in a live application.
import os
from descope import DescopeClient, AuthException
# Ensure DESCOPE_PROJECT_ID and optionally DESCOPE_AUTH_MANAGEMENT_KEY are set as environment variables
project_id = os.environ.get('DESCOPE_PROJECT_ID', '')
management_key = os.environ.get('DESCOPE_AUTH_MANAGEMENT_KEY', '')
# Optional: If using a custom domain
base_url = os.environ.get('DESCOPE_BASE_URI', '')
if not project_id:
print("Error: DESCOPE_PROJECT_ID environment variable is not set.")
exit(1)
try:
# Initialize the DescopeClient
# If base_url is an empty string, it will default to Descope's API endpoint
descope_client = DescopeClient(project_id=project_id, auth_management_key=management_key, base_url=base_url)
print("DescopeClient initialized successfully.")
# Example: Validate a session token (replace 'your_session_token' with an actual token)
# In a real application, this token would come from an incoming request's Authorization header or cookie
test_session_token = "your_session_token"
if test_session_token == "your_session_token":
print("Warning: Please replace 'your_session_token' with a real session token for validation.")
try:
session_jwt = descope_client.validate_session(session_token=test_session_token)
print(f"Session validated successfully. User ID: {session_jwt['sub']}")
except AuthException as e:
print(f"Session validation failed: {e}")
except Exception as e:
print(f"An unexpected error occurred during session validation: {e}")
except AuthException as e:
print(f"Failed to initialize DescopeClient due to authentication error: {e}")
except Exception as e:
print(f"An unexpected error occurred during DescopeClient initialization: {e}")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'descope'
The 'descope' Python package has not been installed in your environment or is not accessible within your Python path.
fixInstall the Descope Python SDK using pip: `pip install descope`
AuthException: Invalid signin credentials
This error typically occurs during an authentication attempt when the provided user credentials (e.g., username/password, OTP) do not match Descope's records or are incorrect.
fixVerify that the `login_id` and password (or other authentication method inputs) are correct. Check the Descope Console for user status (e.g., disabled user, unverified email) or password policy compliance.
failed to initialize. Error: Project ID is required
The DescopeClient was initialized without providing a `project_id`, which is a mandatory parameter for the SDK to function.
fixProvide your Descope Project ID during client initialization. You can find your Project ID in the Descope Console. `descope_client = DescopeClient(project_id='<Your Descope Project ID>')`
AttributeError: 'DescopeClient' object has no attribute 'some_method'
You are attempting to call a method or access an attribute on the `DescopeClient` object that either does not exist, is misspelled, or is not part of the public API for the SDK version you are using.
fixReview the Descope Python SDK documentation for the correct method names and usage. Ensure your SDK version supports the method you are trying to use. For example, if trying to access user management functions, ensure you are calling the correct method, like `descope_client.mgmt.user.load_user_by_login_id()` instead of a non-existent `descope_client.load_user()`.
TypeError: DescopeClient.__init__() missing 1 required positional argument: 'project_id'
The `DescopeClient` constructor was called without providing the mandatory `project_id` argument.
fixfrom descope import DescopeClient
client = DescopeClient(project_id="<YOUR_PROJECT_ID>")
Upgrade
Version history
2.13.0latest on PyPI · released Aug 24, 2026
Audit
Dependencies
No dependency data recorded yet.