{"id":4929,"library":"descope","title":"Descope Python SDK","description":"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.","status":"active","version":"1.12.1","language":"en","source_language":"en","source_url":"https://github.com/descope/python-sdk","tags":["authentication","auth","security","sdk","identity"],"install":[{"cmd":"pip install descope","lang":"bash","label":"Install Descope Python SDK"}],"dependencies":[],"imports":[{"note":"The primary class for interacting with the Descope API.","symbol":"DescopeClient","correct":"from descope import DescopeClient"},{"note":"Common exception for Descope authentication failures.","symbol":"AuthException","correct":"from descope import AuthException"},{"note":"Constants for session and refresh token names, often used with cookies or headers.","symbol":"SESSION_TOKEN_NAME, REFRESH_SESSION_TOKEN_NAME","correct":"from descope import SESSION_TOKEN_NAME, REFRESH_SESSION_TOKEN_NAME"}],"quickstart":{"code":"import os\nfrom descope import DescopeClient, AuthException\n\n# Ensure DESCOPE_PROJECT_ID and optionally DESCOPE_AUTH_MANAGEMENT_KEY are set as environment variables\nproject_id = os.environ.get('DESCOPE_PROJECT_ID', '')\nmanagement_key = os.environ.get('DESCOPE_AUTH_MANAGEMENT_KEY', '')\n# Optional: If using a custom domain\nbase_url = os.environ.get('DESCOPE_BASE_URI', '')\n\nif not project_id:\n    print(\"Error: DESCOPE_PROJECT_ID environment variable is not set.\")\n    exit(1)\n\ntry:\n    # Initialize the DescopeClient\n    # If base_url is an empty string, it will default to Descope's API endpoint\n    descope_client = DescopeClient(project_id=project_id, auth_management_key=management_key, base_url=base_url)\n    print(\"DescopeClient initialized successfully.\")\n\n    # Example: Validate a session token (replace 'your_session_token' with an actual token)\n    # In a real application, this token would come from an incoming request's Authorization header or cookie\n    test_session_token = \"your_session_token\"\n    if test_session_token == \"your_session_token\":\n        print(\"Warning: Please replace 'your_session_token' with a real session token for validation.\")\n    \n    try:\n        session_jwt = descope_client.validate_session(session_token=test_session_token)\n        print(f\"Session validated successfully. User ID: {session_jwt['sub']}\")\n    except AuthException as e:\n        print(f\"Session validation failed: {e}\")\n    except Exception as e:\n        print(f\"An unexpected error occurred during session validation: {e}\")\n\nexcept AuthException as e:\n    print(f\"Failed to initialize DescopeClient due to authentication error: {e}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred during DescopeClient initialization: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"The `DescopeClient` requires a `project_id` for initialization. Failing to provide this will lead to an `AuthException` during client creation or subsequent API calls.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"If 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Provide the `base_url` parameter during `DescopeClient` initialization, or set the `DESCOPE_BASE_URI` environment variable with your custom domain's base URL.","message":"When 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"API 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}