Globus SDK for Python

Common errors

• globus_sdk.exc.GlobusAPIError: 403 Forbidden - 'ConsentRequired'

  cause The application or user lacks the necessary consent (scopes) to perform the requested action. This often happens when the required scopes were not requested during the OAuth2 flow or the user did not grant them.
  fix Ensure all necessary scopes (e.g., `TransferClient.scopes.all`, `AuthClient.scopes.view_identity_set`) are requested in `oauth2_start_flow` or `oauth2_client_credentials_tokens`. Re-run the authentication flow to prompt the user for consent if a user-based flow is used. For automated applications, verify the client has been granted the required scopes.

• globus_sdk.exc.GlobusSDKUsageError: A 'client_secret' is required for ConfidentialAppAuthClient

  cause Attempting to instantiate `ConfidentialAppAuthClient` without providing a `client_secret`, or using it when a `NativeAppAuthClient` would be more appropriate for a public client.
  fix If your application is confidential (can securely store a secret), ensure you provide both `client_id` and `client_secret` to `ConfidentialAppAuthClient`. If your application is a native/public client (e.g., desktop app, CLI), use `NativeAppAuthClient` instead, which does not require a client secret.

• TypeError: TransferData.__init__() got an unexpected keyword argument 'transfer_client'

  cause You are likely using `globus-sdk` v4.0.0 or later, but your code is still passing a `transfer_client` argument to the `TransferData` or `DeleteData` constructors, which was removed in v4.
  fix Remove the `transfer_client` argument from calls to `TransferData(...)` and `DeleteData(...)`. The clients are no longer passed directly into these data constructs.

• globus_sdk.exc.NetworkError: ConnectionRefusedError: [Errno 111] Connection refused

  cause The SDK failed to establish a connection to the Globus API server, likely due to network issues, a firewall blocking the connection, or incorrect proxy settings.
  fix Check your network connectivity and firewall rules. Ensure that outbound connections to Globus API domains (e.g., auth.globus.org, transfer.api.globus.org) are allowed. If using a proxy, ensure environment variables like `HTTP_PROXY` and `HTTPS_PROXY` are correctly configured.

Warnings

• breaking The SDK underwent significant breaking changes between v3.x and v4.0.0. Key changes include `TransferData` and `DeleteData` no longer accepting a `transfer_client` parameter, `AuthClient` no longer directly accepting or exposing `client_id`, and `MutableScope` being removed in favor of `Scope`.
  Fix: Consult the official 'Upgrading' guide for a detailed migration path. Generally, remove `transfer_client` from `TransferData`/`DeleteData` constructors, instantiate `AuthClient` without `client_id` (it's implicit from `NativeAppAuthClient`/`ConfidentialAppAuthClient`), and replace `MutableScope` with `Scope`.
• breaking Support for Python 3.8 was removed in version 4.2.0 of the `globus-sdk`.
  Fix: Upgrade your Python environment to Python 3.9 or newer. The current recommended minimum is Python 3.9.
• gotcha The `globus_sdk.experimental` module contains unstable interfaces (e.g., `TransferClientV2`, `gcs_downloader`). These are subject to breaking changes without a major version bump and are intended for community feedback.
  Fix: Be aware that code using experimental components may break in minor releases. Avoid using them in production for critical features unless you are prepared to adapt to frequent changes. Stable interfaces will eventually move out of `experimental`.
• gotcha Globus SDK client objects hold networking sessions. Using a single client object across multiple processes (e.g., after `fork()` or in separate threads without proper synchronization) is considered unsafe and can lead to unexpected behavior or resource contention.
  Fix: Create service client objects *after* process forking. In multi-processing applications, ensure there is only one service client instance created per process.

Install

• pip install globus-sdk Install latest version

Imports

• AuthClient

  from globus_sdk import AuthClient

• TransferClient

  from globus_sdk import TransferClient

• NativeAppAuthClient

  from globus_sdk import NativeAppAuthClient

  Used for applications that cannot securely store a client secret, like desktop apps or CLI tools.
• ConfidentialAppAuthClient

  from globus_sdk import ConfidentialAppAuthClient

  Used for applications that can securely store a client secret, like web apps or backend services.
• RefreshTokenAuthorizer

  from globus_sdk import RefreshTokenAuthorizer

  The recommended authorizer for long-lived access in user-facing applications.
• FlowsClient

  from globus_sdk import FlowsClient

• SearchClient

  from globus_sdk import SearchClient

Quickstart

This quickstart demonstrates a typical Native App authentication flow to obtain refresh and access tokens, then uses these tokens to create a `TransferClient` and list the user's Globus endpoints. It assumes you have registered a Native App at developers.globus.org and set its redirect URL. For production use, tokens should be stored securely.

import os
import globus_sdk

# NOTE: Register your app at developers.globus.org and get a Client ID.
# For a native app, ensure 'Native App' is checked and set 'Redirects' to
# 'https://auth.globus.org/v2/web/auth-code'
CLIENT_ID = os.environ.get('GLOBUS_CLIENT_ID', 'YOUR_NATIVE_APP_CLIENT_ID')

def authenticate_and_list_endpoints():
    client = globus_sdk.NativeAppAuthClient(CLIENT_ID)
    client.oauth2_start_flow(refresh_tokens=True)

    authorize_url = client.oauth2_get_authorize_url()
    print(f"Please go to this URL and login:\n\n{authorize_url}\n")

    auth_code = input("Please enter the code here: ").strip()
    tokens = client.oauth2_exchange_code_for_tokens(auth_code)

    # Store the tokens securely for future use. For this example, we just extract them.
    transfer_tokens = tokens.by_resource_server['transfer.api.globus.org']
    transfer_access_token = transfer_tokens['access_token']
    transfer_refresh_token = transfer_tokens['refresh_token']

    # Use a RefreshTokenAuthorizer for long-lived access
    authorizer = globus_sdk.RefreshTokenAuthorizer(
        transfer_refresh_token, client, access_token=transfer_access_token
    )
    transfer_client = globus_sdk.TransferClient(authorizer=authorizer)

    print("\nYour Globus endpoints:")
    for ep in transfer_client.endpoint_search(filter_scope='managed'):
        print(f"  {ep['display_name']} (ID: {ep['id']})")

if __name__ == "__main__":
    if CLIENT_ID == 'YOUR_NATIVE_APP_CLIENT_ID':
        print("WARNING: Replace 'YOUR_NATIVE_APP_CLIENT_ID' with your actual Globus Client ID or set the GLOBUS_CLIENT_ID environment variable.")
    authenticate_and_list_endpoints()