0
# Enterprise Features
1

2
Enterprise account management including user administration, audit logging, workspace management, and organizational controls. These features require an Enterprise billing plan and provide advanced administrative capabilities.
3

4
## Capabilities
5

6
### Enterprise Account Management
7

8
Core enterprise account operations including metadata retrieval, user management, and organizational structure access.
9

10
```python { .api }
11
class Enterprise:
12
    def __init__(self, api: object, enterprise_account_id: str):
13
        """
14
        Initialize Enterprise instance.
15
        
16
        Parameters:
17
        - api: Api instance
18
        - enterprise_account_id: Enterprise account ID
19
        """
20
    
21
    def info(self, *, aggregated: bool = False, descendants: bool = False) -> object:
22
        """
23
        Get enterprise account information.
24
        
25
        Parameters:
26
        - aggregated: Include aggregated values across enterprise
27
        - descendants: Include information about descendant organizations
28
        
29
        Returns:
30
        EnterpriseInfo object with account metadata
31
        """
32
    
33
    def create_descendant(self, name: str) -> 'Enterprise':
34
        """
35
        Create descendant enterprise account.
36
        
37
        Parameters:
38
        - name: Name for the new descendant account
39
        
40
        Returns:
41
        Enterprise instance for created account
42
        """
43

44
class Workspace:
45
    def __init__(self, api: object, workspace_id: str):
46
        """
47
        Initialize Workspace instance.
48
        
49
        Parameters:
50
        - api: Api instance  
51
        - workspace_id: Workspace ID (starts with 'wsp')
52
        """
53
    
54
    def create_base(self, name: str, tables: list[dict]) -> object:
55
        """
56
        Create base in workspace.
57
        
58
        Parameters:
59
        - name: Base name
60
        - tables: List of table schema dictionaries
61
        
62
        Returns:
63
        Base instance for created base
64
        """
65
    
66
    def collaborators(self, *, force: bool = False) -> object:
67
        """
68
        Get workspace collaborators and metadata.
69
        
70
        Parameters:
71
        - force: Force refresh cached data
72
        
73
        Returns:
74
        WorkspaceCollaborators object
75
        """
76
    
77
    def bases(self) -> list[object]:
78
        """
79
        Get all bases within workspace.
80
        
81
        Returns:
82
        List of Base instances
83
        """
84
    
85
    @property
86
    def name(self) -> str:
87
        """Workspace name."""
88
    
89
    def delete(self) -> None:
90
        """Delete workspace."""
91
    
92
    def move_base(self, base: Union[str, object], target: Union[str, 'Workspace'], 
93
                  index: Optional[int] = None) -> None:
94
        """
95
        Move base to different workspace.
96
        
97
        Parameters:
98
        - base: Base ID or Base instance to move
99
        - target: Target workspace ID or Workspace instance
100
        - index: Position in target workspace (optional)
101
        """
102
```
103

104
### User Management
105

106
Comprehensive user administration including user retrieval, access control, and account lifecycle management.
107

108
```python { .api }
109
def user(self, id_or_email: str, *, 
110
         collaborations: bool = True,
111
         aggregated: bool = False, 
112
         descendants: bool = False) -> object:
113
    """
114
    Get single user information.
115
    
116
    Parameters:
117
    - id_or_email: User ID (starts with 'usr') or email address
118
    - collaborations: Include collaboration data
119
    - aggregated: Include aggregated values across enterprise
120
    - descendants: Include information per descendant enterprise
121
    
122
    Returns:
123
    UserInfo object with user details
124
    """
125

126
def users(self, ids_or_emails: list[str], *,
127
          collaborations: bool = True,
128
          aggregated: bool = False,
129
          descendants: bool = False) -> list[object]:
130
    """
131
    Get multiple users' information.
132
    
133
    Parameters:
134
    - ids_or_emails: List of user IDs or email addresses (max 100)
135
    - collaborations: Include collaboration data
136
    - aggregated: Include aggregated values
137
    - descendants: Include descendant enterprise information
138
    
139
    Returns:
140
    List of UserInfo objects
141
    """
142

143
def remove_user(self, user_id: str, replacement: Optional[str] = None, *,
144
                descendants: bool = False) -> object:
145
    """
146
    Remove user from enterprise and all associated workspaces/bases.
147
    
148
    Parameters:
149
    - user_id: User ID to remove
150
    - replacement: Replacement owner for sole-owned workspaces
151
    - descendants: Also remove from descendant enterprises
152
    
153
    Returns:
154
    UserRemoved object with removal details
155
    """
156

157
def claim_users(self, users: dict[str, str]) -> object:
158
    """
159
    Manage user membership status (managed vs unmanaged).
160
    
161
    Parameters:
162
    - users: Dict mapping user IDs/emails to 'managed' or 'unmanaged'
163
    
164
    Returns:
165
    ManageUsersResponse object with operation results
166
    """
167

168
def delete_users(self, emails: list[str]) -> object:
169
    """
170
    Delete multiple users by email address.
171
    
172
    Parameters:
173
    - emails: List of email addresses to delete
174
    
175
    Returns:
176
    DeleteUsersResponse object with deletion results
177
    """
178

179
def grant_admin(self, *users: Union[str, object]) -> object:
180
    """
181
    Grant admin access to users.
182
    
183
    Parameters:
184
    - users: User IDs, emails, or UserInfo objects
185
    
186
    Returns:
187
    ManageUsersResponse object
188
    """
189

190
def revoke_admin(self, *users: Union[str, object]) -> object:
191
    """
192
    Revoke admin access from users.
193
    
194
    Parameters:
195
    - users: User IDs, emails, or UserInfo objects
196
    
197
    Returns:
198
    ManageUsersResponse object
199
    """
200
```
201

202
### Group Management
203

204
User group operations for organizing users and managing permissions at scale.
205

206
```python { .api }
207
def group(self, group_id: str, collaborations: bool = True) -> object:
208
    """
209
    Get user group information.
210
    
211
    Parameters:
212
    - group_id: Group ID (starts with 'grp')
213
    - collaborations: Include collaboration data
214
    
215
    Returns:
216
    UserGroup object with group details
217
    """
218

219
def move_groups(self, group_ids: list[str], 
220
                target: Union[str, 'Enterprise']) -> object:
221
    """
222
    Move user groups to different enterprise account.
223
    
224
    Parameters:
225
    - group_ids: List of group IDs to move
226
    - target: Target enterprise ID or Enterprise instance
227
    
228
    Returns:
229
    MoveGroupsResponse object with move results
230
    """
231

232
def move_workspaces(self, workspace_ids: list[str],
233
                    target: Union[str, 'Enterprise']) -> object:
234
    """
235
    Move workspaces to different enterprise account.
236
    
237
    Parameters:
238
    - workspace_ids: List of workspace IDs to move  
239
    - target: Target enterprise ID or Enterprise instance
240
    
241
    Returns:
242
    MoveWorkspacesResponse object with move results
243
    """
244
```
245

246
### Audit Logging
247

248
Comprehensive audit trail functionality for tracking all enterprise activities and changes.
249

250
```python { .api }
251
def audit_log(self, *,
252
              page_size: Optional[int] = None,
253
              page_limit: Optional[int] = None,
254
              sort_asc: Optional[bool] = False,
255
              previous: Optional[str] = None,
256
              next: Optional[str] = None,
257
              start_time: Optional[Union[str, object]] = None,
258
              end_time: Optional[Union[str, object]] = None,
259
              user_id: Optional[Union[str, list[str]]] = None,
260
              event_type: Optional[Union[str, list[str]]] = None,
261
              model_id: Optional[Union[str, list[str]]] = None,
262
              category: Optional[Union[str, list[str]]] = None) -> Iterator[object]:
263
    """
264
    Retrieve audit log events with filtering and pagination.
265
    
266
    Parameters:
267
    - page_size: Events per page (max 100)
268
    - page_limit: Maximum pages to retrieve
269
    - sort_asc: Sort ascending (earliest first) vs descending (latest first)
270
    - previous: Pagination cursor for previous page
271
    - next: Pagination cursor for next page
272
    - start_time: Earliest timestamp to retrieve (inclusive)
273
    - end_time: Latest timestamp to retrieve (inclusive)
274
    - user_id: Filter by originating user ID(s) (max 100)
275
    - event_type: Filter by event type(s) (max 100)
276
    - model_id: Filter by model ID(s) that were affected (max 100)
277
    - category: Filter by event category/categories
278
    
279
    Yields:
280
    AuditLogResponse objects containing events and pagination info
281
    """
282
```
283

284
### Usage Examples
285

286
#### Enterprise Account Setup
287

288
```python
289
from pyairtable import Api
290

291
# Initialize API with enterprise access
292
api = Api('your_enterprise_access_token')
293

294
# Get enterprise instance
295
enterprise = api.enterprise('entYourEnterpriseId')
296

297
# Get enterprise information
298
info = enterprise.info(aggregated=True, descendants=True)
299
print(f"Enterprise: {info.name}")
300
print(f"Total users: {info.user_count}")
301
print(f"Total workspaces: {len(info.workspace_ids)}")
302

303
# List descendant enterprises
304
for descendant in info.descendants or []:
305
    print(f"Descendant: {descendant.name} ({descendant.id})")
306
```
307

308
#### User Management Operations
309

310
```python
311
# Get user information
312
user = enterprise.user('user@company.com', collaborations=True)
313
print(f"User: {user.name} ({user.email})")
314
print(f"Admin: {user.is_admin}")
315
print(f"Workspaces: {len(user.collaborations.workspaces)}")
316

317
# Get multiple users efficiently
318
user_emails = ['user1@company.com', 'user2@company.com', 'user3@company.com']
319
users = enterprise.users(user_emails)
320

321
for user in users:
322
    print(f"{user.name}: {user.state}")  # managed/unmanaged
323

324
# Grant admin access
325
enterprise.grant_admin('user1@company.com', 'usrAnotherUserId')
326

327
# Manage user membership
328
enterprise.claim_users({
329
    'new_user@company.com': 'managed',
330
    'contractor@company.com': 'unmanaged'
331
})
332

333
# Remove user from enterprise
334
removal_result = enterprise.remove_user(
335
    'departing_user@company.com',
336
    replacement='replacement_owner@company.com'
337
)
338
print(f"Removed as admin: {removal_result.was_user_removed_as_admin}")
339
```
340

341
#### Workspace Management
342

343
```python
344
# Get workspace
345
workspace = api.workspace('wspmhESAta6clCCwF')
346

347
# Get workspace details
348
collaborators = workspace.collaborators()
349
print(f"Workspace: {collaborators.name}")
350
print(f"Collaborators: {len(collaborators.collaborators)}")
351

352
# List bases in workspace
353
bases = workspace.bases()
354
for base in bases:
355
    print(f"Base: {base.name} ({base.id})")
356

357
# Create new base in workspace
358
new_base = workspace.create_base(
359
    name='New Project Base',
360
    tables=[
361
        {
362
            'name': 'Tasks',
363
            'fields': [
364
                {'name': 'Name', 'type': 'singleLineText'},
365
                {'name': 'Status', 'type': 'singleSelect', 
366
                 'options': {'choices': [{'name': 'Todo'}, {'name': 'Done'}]}},
367
                {'name': 'Due Date', 'type': 'date'}
368
            ]
369
        }
370
    ]
371
)
372
print(f"Created base: {new_base.id}")
373

374
# Move base between workspaces
375
source_workspace = api.workspace('wspmhESAta6clCCwF')
376
target_workspace = api.workspace('wspAnotherWorkspace')
377

378
source_workspace.move_base(
379
    base=new_base,
380
    target=target_workspace,
381
    index=0  # Move to first position
382
)
383
```
384

385
#### Audit Log Monitoring
386

387
```python
388
from datetime import datetime, timedelta
389

390
# Get recent audit events
391
recent_events = []
392
for page in enterprise.audit_log(
393
    sort_asc=False,  # Latest first
394
    page_size=100,
395
    page_limit=5,    # First 5 pages
396
    start_time=datetime.now() - timedelta(days=7)  # Last week
397
):
398
    recent_events.extend(page.events)
399

400
print(f"Found {len(recent_events)} events in last week")
401

402
# Filter by specific event types
403
security_events = enterprise.audit_log(
404
    event_type=['user.created', 'user.deleted', 'admin.granted', 'admin.revoked'],
405
    start_time=datetime.now() - timedelta(days=30)
406
)
407

408
for page in security_events:
409
    for event in page.events:
410
        print(f"{event.event_time}: {event.event_type} by {event.originating_user_id}")
411

412
# Monitor specific users' activities
413
user_activities = enterprise.audit_log(
414
    user_id=['usr1234567890abcd', 'usr0987654321fedc'],
415
    category=['data'],  # Data-related events only
416
    sort_asc=True
417
)
418

419
for page in user_activities:
420
    for event in page.events:
421
        print(f"{event.originating_user_id}: {event.event_type} on {event.model_id}")
422
```
423

424
#### Enterprise Organization Management
425

426
```python
427
# Create descendant enterprise (for Enterprise Hub customers)
428
child_enterprise = enterprise.create_descendant('Regional Office East')
429
print(f"Created descendant: {child_enterprise.id}")
430

431
# Move user groups between enterprises
432
group_move_result = enterprise.move_groups(
433
    group_ids=['grp1234567890abcd', 'grp0987654321fedc'],
434
    target=child_enterprise
435
)
436

437
print(f"Moved groups: {len(group_move_result.moved_groups)}")
438
if group_move_result.errors:
439
    for error in group_move_result.errors:
440
        print(f"Error moving {error.id}: {error.message}")
441

442
# Move workspaces between enterprises
443
workspace_move_result = enterprise.move_workspaces(
444
    workspace_ids=['wspmhESAta6clCCwF'],
445
    target='entAnotherEnterpriseId'
446
)
447

448
print(f"Moved workspaces: {len(workspace_move_result.moved_workspaces)}")
449
```
450

451
#### Advanced User Group Management
452

453
```python
454
# Get group information
455
group = enterprise.group('grp1234567890abcd', collaborations=True)
456
print(f"Group: {group.name}")
457
print(f"Members: {len(group.user_ids)}")
458

459
# Access group collaborations
460
for workspace_collab in group.collaborations.workspaces:
461
    print(f"Workspace {workspace_collab.workspace_id}: {workspace_collab.permission_level}")
462

463
for base_collab in group.collaborations.bases:
464
    print(f"Base {base_collab.base_id}: {base_collab.permission_level}")
465
```
466

467
#### Bulk User Operations
468

469
```python
470
# Process all enterprise users
471
all_user_ids = enterprise.info().user_ids
472
inactive_users = []
473

474
# Check users in batches (API limit: 100 per request)
475
for i in range(0, len(all_user_ids), 100):
476
    batch = all_user_ids[i:i+100]
477
    users = enterprise.users(batch, collaborations=True)
478
    
479
    for user in users:
480
        # Find users with no recent activity
481
        if not user.collaborations.bases and not user.collaborations.workspaces:
482
            inactive_users.append(user.email)
483

484
print(f"Found {len(inactive_users)} inactive users")
485

486
# Bulk manage inactive users
487
if inactive_users:
488
    # Convert to unmanaged status
489
    user_changes = {email: 'unmanaged' for email in inactive_users[:50]}  # First 50
490
    result = enterprise.claim_users(user_changes)
491
    
492
    if result.errors:
493
        for error in result.errors:
494
            print(f"Error processing {error.email}: {error.message}")
495
```