0
# Globus SDK
1

2
A comprehensive Python SDK for the Globus platform, providing programmatic access to research data management services including data transfer, authentication, compute execution, workflow automation, and more. The Globus SDK enables seamless integration with the Globus ecosystem for scientific computing and collaboration workflows.
3

4
## Package Information
5

6
- **Package Name**: globus-sdk
7
- **Version**: 3.62.0
8
- **Language**: Python
9
- **Installation**: `pip install globus-sdk`
10

11
## Core Imports
12

13
```python
14
import globus_sdk
15
```
16

17
Common service-specific imports:
18

19
```python
20
from globus_sdk import (
21
    TransferClient, 
22
    AuthClient,
23
    ComputeClientV3,
24
    FlowsClient,
25
    GroupsClient,
26
    SearchClient,
27
    GCSClient,
28
    TimersClient
29
)
30
```
31

32
## Basic Usage
33

34
### Authentication and Authorization
35

36
The Globus SDK supports multiple authentication patterns using authorizers:
37

38
```python
39
from globus_sdk import (
40
    AccessTokenAuthorizer, 
41
    TransferClient, 
42
    AuthClient,
43
    NativeAppAuthClient
44
)
45

46
# Using an access token directly
47
authorizer = AccessTokenAuthorizer("your_access_token")
48
client = TransferClient(authorizer=authorizer)
49

50
# OAuth2 flow for native applications
51
auth_client = NativeAppAuthClient("your_client_id")
52
auth_client.oauth2_start_flow()
53

54
# Get authorization URL for user
55
authorize_url = auth_client.oauth2_get_authorize_url()
56
print(f"Go to: {authorize_url}")
57

58
# Exchange authorization code for tokens
59
auth_code = input("Enter authorization code: ")
60
token_response = auth_client.oauth2_exchange_code_for_tokens(auth_code)
61

62
# Create authorizer with access token
63
transfer_token = token_response.by_resource_server['transfer.api.globus.org']
64
transfer_authorizer = AccessTokenAuthorizer(transfer_token['access_token'])
65
tc = TransferClient(authorizer=transfer_authorizer)
66
```
67

68
### Data Transfer Operations
69

70
```python
71
from globus_sdk import TransferClient, TransferData
72

73
# Initialize client
74
tc = TransferClient(authorizer=authorizer)
75

76
# Create a transfer operation
77
transfer_data = TransferData(
78
    source_endpoint="source_endpoint_id",
79
    destination_endpoint="dest_endpoint_id",
80
    label="My Transfer"
81
)
82

83
# Add items to transfer
84
transfer_data.add_item("/source/path/file.txt", "/dest/path/file.txt")
85
transfer_data.add_item("/source/dir/", "/dest/dir/", recursive=True)
86

87
# Submit the transfer
88
response = tc.submit_transfer(transfer_data)
89
task_id = response["task_id"]
90
print(f"Transfer submitted: {task_id}")
91

92
# Monitor transfer status
93
status = tc.get_task(task_id)
94
print(f"Status: {status['status']}")
95
```
96

97
### Application Framework
98

99
```python
100
from globus_sdk import UserApp, AuthClient, TransferClient
101

102
# Modern application-centric approach
103
app = UserApp(
104
    "my-app-name",
105
    client_id="your_client_id"
106
)
107

108
# Clients automatically use the app for authentication
109
auth_client = AuthClient(app=app)
110
transfer_client = TransferClient(app=app)
111

112
# The app manages tokens and scopes automatically
113
```
114

115
## Architecture
116

117
The Globus SDK follows consistent design patterns across all services:
118

119
### Service Client Pattern
120
- All service clients inherit from `BaseClient`
121
- Consistent initialization with `app` or `authorizer` parameters
122
- Unified HTTP methods (`get`, `post`, `put`, `patch`, `delete`)
123
- Service-specific error handling with `APIError` subclasses
124

125
### Response Wrapper Pattern  
126
- All API responses wrapped in `GlobusHTTPResponse` or specialized subclasses
127
- Dictionary-like access to response data
128
- Consistent pagination support via `IterableResponse`
129
- Rich response metadata (status codes, headers, etc.)
130

131
### Authorization Strategy Pattern
132
- Multiple authorizer implementations for different auth flows
133
- Consistent `GlobusAuthorizer` interface
134
- Support for OAuth2 flows, client credentials, access tokens, and auto-renewal
135

136
### Scope Management System
137
- Type-safe scope construction with service-specific `ScopeBuilder` objects  
138
- Dynamic scope resolution for collections and flows
139
- Dependency handling for complex permission requirements
140

141
## Capabilities
142

143
### Authentication Service
144

145
OAuth2 flows, token management, identity resolution, and authorization for native and confidential applications. Supports authorization code, client credentials, and refresh token flows with comprehensive consent management.
146

147
```python { .api }
148
class AuthClient(BaseClient):
149
    """General Auth API client for identity and authorization operations."""
150
    
151
    def __init__(
152
        self, 
153
        *, 
154
        app: GlobusApp | None = None,
155
        authorizer: GlobusAuthorizer | None = None,
156
        **kwargs
157
    ) -> None: ...
158
    
159
    def get_identities(
160
        self, 
161
        *, 
162
        usernames: list[str] | None = None,
163
        ids: list[str] | None = None,
164
        **params
165
    ) -> GetIdentitiesResponse: ...
166
    
167
    def get_identity_providers(self, **params) -> GlobusHTTPResponse: ...
168

169
class NativeAppAuthClient(AuthLoginClient):
170
    """OAuth client for native applications (public clients)."""
171
    
172
    def __init__(self, client_id: str, **kwargs) -> None: ...
173
    
174
    def oauth2_start_flow(
175
        self, 
176
        *, 
177
        requested_scopes: str | None = None,
178
        refresh_tokens: bool = False,
179
        prefill_named_grant: str | None = None
180
    ) -> None: ...
181
    
182
    def oauth2_get_authorize_url(self, **params) -> str: ...
183
    
184
    def oauth2_exchange_code_for_tokens(
185
        self, 
186
        auth_code: str
187
    ) -> OAuthTokenResponse: ...
188

189
class ConfidentialAppAuthClient(AuthLoginClient):
190
    """OAuth client for confidential applications (server-side apps)."""
191
    
192
    def __init__(
193
        self, 
194
        client_id: str, 
195
        client_secret: str, 
196
        **kwargs
197
    ) -> None: ...
198
    
199
    def oauth2_client_credentials_tokens(
200
        self, 
201
        *, 
202
        requested_scopes: str | None = None
203
    ) -> OAuthClientCredentialsResponse: ...
204
```
205

206
[Authentication Service](./auth-service.md)
207

208
### Transfer Service
209

210
High-performance data movement between Globus endpoints with support for large files, directories, checksums, and advanced transfer options. Includes endpoint management, activation, and task monitoring.
211

212
```python { .api }
213
class TransferClient(BaseClient):
214
    """Client for Globus Transfer API operations."""
215
    
216
    def __init__(
217
        self,
218
        *,
219
        app: GlobusApp | None = None,
220
        authorizer: GlobusAuthorizer | None = None,
221
        **kwargs
222
    ) -> None: ...
223
    
224
    def submit_transfer(self, data: TransferData) -> GlobusHTTPResponse: ...
225
    
226
    def submit_delete(self, data: DeleteData) -> GlobusHTTPResponse: ...
227
    
228
    def get_task(self, task_id: str, **params) -> GlobusHTTPResponse: ...
229
    
230
    def task_list(
231
        self, 
232
        *, 
233
        limit: int | None = None,
234
        offset: int | None = None,
235
        **params
236
    ) -> IterableTransferResponse: ...
237
    
238
    def endpoint_search(
239
        self, 
240
        filter_fulltext: str | None = None, 
241
        *, 
242
        limit: int | None = None,
243
        offset: int | None = None,
244
        **params
245
    ) -> IterableTransferResponse: ...
246
    
247
    def get_endpoint(self, endpoint_id: str) -> GlobusHTTPResponse: ...
248
```
249

250
[Transfer Service](./transfer-service.md)
251

252
### Compute Service
253

254
Function execution and management on Globus Compute endpoints with support for Python functions, containers, and distributed computing patterns.
255

256
```python { .api }  
257
class ComputeClientV3(BaseClient):
258
    """Client for Globus Compute API v3."""
259
    
260
    def __init__(
261
        self,
262
        *,
263
        app: GlobusApp | None = None,
264
        authorizer: GlobusAuthorizer | None = None,
265
        **kwargs
266
    ) -> None: ...
267
    
268
    def submit_function(
269
        self, 
270
        function_document: ComputeFunctionDocument
271
    ) -> GlobusHTTPResponse: ...
272
    
273
    def get_function(self, function_uuid: str) -> GlobusHTTPResponse: ...
274
    
275
    def submit_task(
276
        self, 
277
        endpoint_uuid: str, 
278
        function_uuid: str, 
279
        function_args: list | None = None,
280
        function_kwargs: dict | None = None
281
    ) -> GlobusHTTPResponse: ...
282
    
283
    def get_task(self, task_uuid: str) -> GlobusHTTPResponse: ...
284
```
285

286
[Compute Service](./compute-service.md)
287

288
### Flows Service  
289

290
Workflow automation and orchestration for complex multi-step operations across Globus services with conditional logic, error handling, and state management.
291

292
```python { .api }
293
class FlowsClient(BaseClient):
294
    """Client for Globus Flows service operations."""
295
    
296
    def __init__(
297
        self,
298
        *,
299
        app: GlobusApp | None = None,
300
        authorizer: GlobusAuthorizer | None = None,
301
        **kwargs
302
    ) -> None: ...
303
    
304
    def create_flow(
305
        self, 
306
        title: str, 
307
        definition: dict, 
308
        *, 
309
        input_schema: dict | None = None,
310
        **kwargs
311
    ) -> GlobusHTTPResponse: ...
312
    
313
    def get_flow(self, flow_id: str) -> GlobusHTTPResponse: ...
314
    
315
    def run_flow(
316
        self, 
317
        flow_id: str, 
318
        flow_input: dict, 
319
        *, 
320
        flow_scope: str | None = None,
321
        **kwargs
322
    ) -> GlobusHTTPResponse: ...
323
```
324

325
[Flows Service](./flows-service.md)
326

327
### Globus Connect Server Management
328

329
Configuration and management of Globus Connect Server endpoints, collections, storage gateways, and access policies for institutional data sharing.
330

331
```python { .api }
332
class GCSClient(BaseClient):
333
    """Client for Globus Connect Server management operations."""
334
    
335
    def __init__(
336
        self,
337
        *,
338
        app: GlobusApp | None = None,
339
        authorizer: GlobusAuthorizer | None = None,
340
        **kwargs
341
    ) -> None: ...
342
    
343
    def create_endpoint(self, data: EndpointDocument) -> UnpackingGCSResponse: ...
344
    
345
    def get_endpoint(self, endpoint_id: str) -> UnpackingGCSResponse: ...
346
    
347
    def create_collection(self, data: CollectionDocument) -> UnpackingGCSResponse: ...
348
    
349
    def get_collection(self, collection_id: str) -> UnpackingGCSResponse: ...
350
```
351

352
[GCS Service](./gcs-service.md)
353

354
### Groups Service
355

356
Group membership management, access control, and policy configuration for collaborative research with fine-grained permission controls.
357

358
```python { .api }
359
class GroupsClient(BaseClient):
360
    """Client for Globus Groups service operations."""
361
    
362
    def __init__(
363
        self,
364
        *,
365
        app: GlobusApp | None = None,
366
        authorizer: GlobusAuthorizer | None = None,
367
        **kwargs
368
    ) -> None: ...
369
    
370
    def create_group(
371
        self, 
372
        name: str, 
373
        *, 
374
        description: str | None = None,
375
        **kwargs
376
    ) -> GlobusHTTPResponse: ...
377
    
378
    def get_group(self, group_id: str, **params) -> GlobusHTTPResponse: ...
379
    
380
    def add_member(
381
        self, 
382
        group_id: str, 
383
        identity_id: str, 
384
        *, 
385
        role: GroupRole = GroupRole.member
386
    ) -> GlobusHTTPResponse: ...
387
```
388

389
[Groups Service](./groups-service.md)
390

391
### Search Service
392

393
Metadata indexing and search capabilities for research data discovery with support for custom schemas, faceted search, and real-time indexing.
394

395
```python { .api }
396
class SearchClient(BaseClient):
397
    """Client for Globus Search service operations."""
398
    
399
    def __init__(
400
        self,
401
        *,
402
        app: GlobusApp | None = None,
403
        authorizer: GlobusAuthorizer | None = None,
404
        **kwargs
405
    ) -> None: ...
406
    
407
    def search(
408
        self, 
409
        index_id: str, 
410
        q: str, 
411
        *, 
412
        limit: int | None = None,
413
        offset: int | None = None,
414
        **params
415
    ) -> GlobusHTTPResponse: ...
416
    
417
    def post_search(
418
        self, 
419
        index_id: str, 
420
        data: SearchQuery | dict
421
    ) -> GlobusHTTPResponse: ...
422
```
423

424
[Search Service](./search-service.md)
425

426
### Timer Service
427

428
Scheduled task execution and automation with support for one-time and recurring schedules, complex timing patterns, and integration with other Globus services.
429

430
```python { .api }
431
class TimersClient(BaseClient):
432
    """Client for Globus Timers service operations."""
433
    
434
    def __init__(
435
        self,
436
        *,
437
        app: GlobusApp | None = None, 
438
        authorizer: GlobusAuthorizer | None = None,
439
        **kwargs
440
    ) -> None: ...
441
    
442
    def create_timer(
443
        self,
444
        timer: TimerJob | TransferTimer,
445
    ) -> GlobusHTTPResponse: ...
446
    
447
    def get_timer(self, timer_id: str) -> GlobusHTTPResponse: ...
448
    
449
    def list_timers(
450
        self, 
451
        *, 
452
        limit: int | None = None,
453
        **params
454
    ) -> GlobusHTTPResponse: ...
455
```
456

457
[Timer Service](./timers-service.md)
458

459
### Core Framework
460

461
Foundation classes for authorization, HTTP clients, response handling, scope management, and error handling that provide consistent patterns across all Globus services.
462

463
```python { .api }
464
class BaseClient:
465
    """Abstract base class for all Globus API clients."""
466
    
467
    def __init__(
468
        self,
469
        *,
470
        app: GlobusApp | None = None,
471
        authorizer: GlobusAuthorizer | None = None,
472
        app_name: str | None = None,
473
        base_url: str | None = None,
474
        **kwargs
475
    ) -> None: ...
476
    
477
    def get(
478
        self, 
479
        path: str, 
480
        *, 
481
        query_params: dict[str, Any] | None = None,
482
        **kwargs
483
    ) -> GlobusHTTPResponse: ...
484
    
485
    def post(
486
        self, 
487
        path: str, 
488
        *, 
489
        data: Any = None,
490
        **kwargs
491
    ) -> GlobusHTTPResponse: ...
492

493
class GlobusHTTPResponse:
494
    """Response wrapper providing dict-like access to API response data."""
495
    
496
    @property
497
    def data(self) -> Any: ...
498
    
499
    @property 
500
    def http_status(self) -> int: ...
501
    
502
    def __getitem__(self, key: str) -> Any: ...
503
    
504
    def get(self, key: str, default: Any = None) -> Any: ...
505
```
506

507
[Core Framework](./core-framework.md)