Box Python SDK

Warnings

• breaking Version 10.0.0 of `boxsdk` entirely replaces the old, manually maintained `boxsdk` package with the auto-generated `box_sdk_gen`. This introduces a new interface for all methods and requires changes to import paths (e.g., `from box_sdk_gen import ...` instead of `from boxsdk import ...`) and potentially client/auth object instantiation.
  Fix: Migrate your codebase to use imports and classes from the `box_sdk_gen` package. Consult the official migration guides for detailed steps.
• deprecated Box Next Generation SDKs, which were developed in parallel, are deprecated as of September 17, 2025. While existing code will continue to function, these separate artifacts will no longer receive new features, updates, or bug fixes. Their functionalities are now integrated into the consolidated Box core SDKs (v4.x.y and v10.x.y).
  Fix: Upgrade to Box core SDK v10.x.x (recommended for new applications) or v4.x.x (for existing `boxsdk` users to access generated features while gradually migrating).
• gotcha Common authentication issues (e.g., 'Access denied - insufficient permission', 'No "refresh_token" parameter found', 'The "box_subject_type" value is unauthorized') often stem from misconfiguration in the Box Developer Console or not meeting prerequisites for specific authentication methods (e.g., administrator approval for Client Credentials Grant).
  Fix: Carefully review the Box Developer Console application settings and ensure they align with the chosen authentication method (OAuth 2.0, JWT, Client Credentials Grant, Developer Token). Verify client IDs, secrets, public/private keys, and ensure the application has the necessary permissions and administrator approval for your enterprise.
• gotcha Achieving FIPS 140-2 compliance when using the SDK, especially with JWT, requires specific setup. Python's default distributions often link against OpenSSL v1.1.1 (not FIPS compliant). You must ensure Python uses a custom SSL library (like OpenSSL 3.0) and that the `cryptography` library (a JWT dependency) is also installed with a FIPS-compliant OpenSSL version.
  Fix: Refer to Box's FIPS 140-2 compliance documentation. This typically involves building a custom Python distribution with OpenSSL 3.0 and ensuring `cryptography` is installed correctly against it.
• gotcha Box SDK uses a modified Semantic Versioning. While `PATCH` releases are generally safe, `MINOR` versions can introduce small breaking changes, primarily to function signatures. `MAJOR` versions denote significant, potentially extensive breaking changes.
  Fix: Pin your project's `boxsdk` dependency to at least the major version (`boxsdk~=10.0` or `boxsdk==10.*`) to avoid unexpected breaking changes from minor version increments. Review changelogs for minor updates.

Install

• pip install boxsdk>=10 Standard Installation
• pip install "boxsdk[jwt]>=10" With JWT Authentication Dependencies

Imports

• BoxClient, BoxDeveloperTokenAuth

  from box_sdk_gen import BoxClient, BoxDeveloperTokenAuth

  As of v10, the SDK uses `box_sdk_gen` exclusively. Direct imports from `boxsdk` for client and auth classes are deprecated for new codebases or migrations to v10.

Quickstart

This quickstart demonstrates how to authenticate with a Developer Token and list the items in your Box root folder using the v10+ SDK's `box_sdk_gen` package. Ensure you replace 'YOUR_DEVELOPER_TOKEN' with an actual token or set the `BOX_DEVELOPER_TOKEN` environment variable.

import os
from box_sdk_gen import BoxClient, BoxDeveloperTokenAuth

# Get your Developer Token from the Box Developer Console for testing.
# It's recommended to use environment variables for sensitive information.
DEVELOPER_TOKEN = os.environ.get('BOX_DEVELOPER_TOKEN', 'YOUR_DEVELOPER_TOKEN')

def get_root_folder_items(token: str):
    if not token or token == 'YOUR_DEVELOPER_TOKEN':
        print("Please set the 'BOX_DEVELOPER_TOKEN' environment variable or replace 'YOUR_DEVELOPER_TOKEN' in the script.")
        return

    try:
        auth: BoxDeveloperTokenAuth = BoxDeveloperTokenAuth(token=token)
        client: BoxClient = BoxClient(auth=auth)

        # Get items in the root folder (folder ID '0')
        print("\nItems in your Box root folder:")
        for item in client.folders.get_folder_items('0').entries:
            print(f"- {item.name} ({item.type.value})")

    except Exception as e:
        print(f"An error occurred: {e}")

if __name__ == '__main__':
    get_root_folder_items(DEVELOPER_TOKEN)