Registry / auth-security / descope

descope

JSON →
library2.13.0pypypi✓ verified 23d ago

The Descope Python SDK provides convenient access to Descope's user management and authentication APIs for backend applications. It facilitates secure user authentication, session management, and various identity-related operations. The library is actively maintained with frequent updates, ensuring compatibility with the latest Descope platform features.

pip install descope
INSTALL
IMPORT
SIG · DESCOPE
D
descope
auth-securitypythonv2.13.0
Install
3.5s avg
Import
1008ms
Disk
43MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 1.052s · 44MB
glibc
py 3.103.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}")
Debug
Known issues
gotchaThe `DescopeClient` requires a `project_id` for initialization. Failing to provide this will lead to an `AuthException` during client creation or subsequent API calls.
fix
Ensure the `DESCOPE_PROJECT_ID` environment variable is set or pass `project_id` directly during `DescopeClient` instantiation. Obtain your project ID from the Descope Console.
affects: All versions
gotchaIf public access to authentication APIs is disabled in your Descope project settings, you must provide a management key to perform authentication API calls. Without it, these calls will fail.
fix
Set the `DESCOPE_AUTH_MANAGEMENT_KEY` environment variable or pass the `auth_management_key` parameter when initializing `DescopeClient`. The management key needs 'Authentication / Full Access' permissions.
affects: All versions
gotchaWhen using a custom domain for your Descope project, you must explicitly set the `base_url` during `DescopeClient` initialization. Otherwise, the SDK will attempt to use the default Descope API endpoint, leading to incorrect routing.
fix
Provide the `base_url` parameter during `DescopeClient` initialization, or set the `DESCOPE_BASE_URI` environment variable with your custom domain's base URL.
affects: All versions
gotchaAPI requests can fail with 'Invalid JSON Payload' errors if the JSON data sent is malformed. Common mistakes include missing commas, incorrect use of brackets/braces, or using single quotes instead of double quotes for keys and string values.
fix
Always validate your JSON payload structure. Use double quotes for all keys and string values, ensure proper comma placement, and verify that all opening brackets/braces have corresponding closing ones.
affects: All versions
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.
fix
Install 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.
fix
Verify 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.
fix
Provide 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.
fix
Review 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.
fix
from 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.

Agent activity
25 hits · last 30 days
node
22
OpenAI (training)
1
Resources
descope — pip install descope · libregistry