Descope Python SDK

Warnings

• gotcha The `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.
• gotcha 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.
  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.
• gotcha 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.
  Fix: Provide the `base_url` parameter during `DescopeClient` initialization, or set the `DESCOPE_BASE_URI` environment variable with your custom domain's base URL.
• gotcha 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.
  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.

Install

• pip install descope Install Descope Python SDK

Imports

• 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.

Quickstart

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}")