0
# Provisioning API
1

2
Comprehensive account and user management functionality for Cloudinary multi-tenant environments. Manage sub-accounts, users, user groups, and access keys programmatically.
3

4
## Capabilities
5

6
### Sub-Account Management
7

8
Create and manage sub-accounts for multi-tenant cloud environments.
9

10
```python { .api }
11
def sub_accounts(enabled=None, ids=None, prefix=None, **options):
12
    """List all sub-accounts.
13
    
14
    Args:
15
        enabled (bool, optional): Filter by enabled status. 
16
            True for enabled accounts, False for disabled, None for all
17
        ids (list, optional): List of specific sub-account IDs to retrieve (up to 100).
18
            When provided, other filters are ignored
19
        prefix (str, optional): Search by sub-account name prefix (case-insensitive)
20
        **options: Additional API options
21
    
22
    Returns:
23
        dict: Sub-accounts list containing:
24
            - sub_accounts (list): Array of sub-account objects
25
            - total_count (int): Total number of matching sub-accounts
26
    """
27

28
def create_sub_account(name, cloud_name=None, custom_attributes=None, enabled=None, base_account=None, **options):
29
    """Create a new sub-account.
30
    
31
    Args:
32
        name (str): Display name for the new sub-account
33
        cloud_name (str, optional): Unique cloud name (alphanumeric and underscores only).
34
            Must be unique across all Cloudinary accounts
35
        custom_attributes (dict, optional): Custom key-value attributes to associate
36
        enabled (bool, optional): Whether to create as enabled (default: True)
37
        base_account (str, optional): ID of existing sub-account to copy settings from
38
        **options: Additional API options
39
    
40
    Returns:
41
        dict: Created sub-account details containing:
42
            - id (str): Unique sub-account identifier
43
            - name (str): Display name
44
            - cloud_name (str): Cloud name for API access
45
            - enabled (bool): Account status
46
            - created_at (str): Creation timestamp
47
            - custom_attributes (dict): Custom attributes
48
    """
49

50
def sub_account(sub_account_id, **options):
51
    """Get details of a specific sub-account.
52
    
53
    Args:
54
        sub_account_id (str): The ID of the sub-account to retrieve
55
        **options: Additional API options
56
    
57
    Returns:
58
        dict: Sub-account details with all properties
59
    """
60

61
def update_sub_account(sub_account_id, name=None, cloud_name=None, custom_attributes=None, enabled=None, **options):
62
    """Update an existing sub-account.
63
    
64
    Args:
65
        sub_account_id (str): The ID of the sub-account to update
66
        name (str, optional): New display name
67
        cloud_name (str, optional): New cloud name (must be unique)
68
        custom_attributes (dict, optional): Updated custom attributes
69
        enabled (bool, optional): Enable or disable the account
70
        **options: Additional API options
71
    
72
    Returns:
73
        dict: Updated sub-account details
74
    """
75

76
def delete_sub_account(sub_account_id, **options):
77
    """Delete a sub-account permanently.
78
    
79
    Args:
80
        sub_account_id (str): The ID of the sub-account to delete
81
        **options: Additional API options
82
    
83
    Returns:
84
        dict: Deletion result containing:
85
            - message (str): Confirmation message
86
    """
87
```
88

89
### User Management
90

91
Create and manage users with role-based access control.
92

93
```python { .api }
94
def users(user_ids=None, sub_account_id=None, pending=None, prefix=None, last_login=None, from_date=None, to_date=None, **options):
95
    """List users with filtering options.
96
    
97
    Args:
98
        user_ids (list, optional): Specific user IDs to retrieve
99
        sub_account_id (str, optional): Filter by users with access to this sub-account
100
        pending (bool, optional): Filter by pending status.
101
            True for pending users, False for confirmed, None for all
102
        prefix (str, optional): Filter by username prefix
103
        last_login (bool, optional): Filter by last login date range.
104
            True for users who logged in during date range, False for those who didn't
105
        from_date (datetime, optional): Start date for last_login filter
106
        to_date (datetime, optional): End date for last_login filter
107
        **options: Additional API options
108
    
109
    Returns:
110
        dict: Users list containing:
111
            - users (list): Array of user objects
112
            - total_count (int): Total number of matching users
113
    """
114

115
def create_user(name, email, role, sub_account_ids=None, **options):
116
    """Create a new user account.
117
    
118
    Args:
119
        name (str): Username for the new user
120
        email (str): Email address (must be unique)
121
        role (str): User role. Use Role class constants:
122
            - Role.MASTER_ADMIN: Full access across all accounts
123
            - Role.ADMIN: Administrative access to assigned sub-accounts
124
            - Role.BILLING: Billing and usage access
125
            - Role.TECHNICAL_ADMIN: Technical configuration access
126
            - Role.REPORTS: Read-only reporting access
127
            - Role.MEDIA_LIBRARY_ADMIN: Media library management
128
            - Role.MEDIA_LIBRARY_USER: Media library user access
129
        sub_account_ids (list, optional): Sub-accounts this user can access.
130
            Ignored if role is master_admin
131
        **options: Additional API options
132
    
133
    Returns:
134
        dict: Created user details containing:
135
            - id (str): Unique user identifier
136
            - name (str): Username
137
            - email (str): Email address
138
            - role (str): Assigned role
139
            - enabled (bool): Account status
140
            - sub_account_ids (list): Accessible sub-accounts
141
            - created_at (str): Creation timestamp
142
    """
143

144
def user(user_id, **options):
145
    """Get details of a specific user.
146
    
147
    Args:
148
        user_id (str): The ID of the user to retrieve
149
        **options: Additional API options
150
    
151
    Returns:
152
        dict: User details with all properties
153
    """
154

155
def update_user(user_id, name=None, email=None, role=None, sub_account_ids=None, **options):
156
    """Update an existing user account.
157
    
158
    Args:
159
        user_id (str): The ID of the user to update
160
        name (str, optional): New username
161
        email (str, optional): New email address
162
        role (str, optional): New role (use Role class constants)
163
        sub_account_ids (list, optional): Updated list of accessible sub-accounts.
164
            Ignored if role is master_admin
165
        **options: Additional API options
166
    
167
    Returns:
168
        dict: Updated user details
169
    """
170

171
def delete_user(user_id, **options):
172
    """Delete a user account permanently.
173
    
174
    Args:
175
        user_id (str): The ID of the user to delete
176
        **options: Additional API options
177
    
178
    Returns:
179
        dict: Deletion result containing:
180
            - message (str): Confirmation message
181
    """
182
```
183

184
### User Groups
185

186
Organize users into groups for easier access management.
187

188
```python { .api }
189
def user_groups(**options):
190
    """List all user groups.
191
    
192
    Args:
193
        **options: Additional API options
194
    
195
    Returns:
196
        dict: User groups list containing:
197
            - user_groups (list): Array of user group objects
198
            - total_count (int): Total number of groups
199
    """
200

201
def create_user_group(name, **options):
202
    """Create a new user group.
203
    
204
    Args:
205
        name (str): Name for the new user group
206
        **options: Additional API options
207
    
208
    Returns:
209
        dict: Created user group details containing:
210
            - id (str): Unique group identifier
211
            - name (str): Group name
212
            - users_count (int): Number of users in the group
213
            - created_at (str): Creation timestamp
214
    """
215

216
def user_group(user_group_id, **options):
217
    """Get details of a specific user group.
218
    
219
    Args:
220
        user_group_id (str): The ID of the user group to retrieve
221
        **options: Additional API options
222
    
223
    Returns:
224
        dict: User group details with all properties
225
    """
226

227
def update_user_group(user_group_id, name, **options):
228
    """Update an existing user group.
229
    
230
    Args:
231
        user_group_id (str): The ID of the user group to update
232
        name (str): New group name
233
        **options: Additional API options
234
    
235
    Returns:
236
        dict: Updated user group details
237
    """
238

239
def delete_user_group(user_group_id, **options):
240
    """Delete a user group permanently.
241
    
242
    Args:
243
        user_group_id (str): The ID of the user group to delete
244
        **options: Additional API options
245
    
246
    Returns:
247
        dict: Deletion result containing:
248
            - message (str): Confirmation message
249
    """
250
```
251

252
### Group Membership Management
253

254
Add and remove users from groups, and query group memberships.
255

256
```python { .api }
257
def add_user_to_group(user_group_id, user_id, **options):
258
    """Add a user to a user group.
259
    
260
    Args:
261
        user_group_id (str): The ID of the user group
262
        user_id (str): The ID of the user to add
263
        **options: Additional API options
264
    
265
    Returns:
266
        dict: Updated group membership containing:
267
            - users (list): Current list of users in the group
268
    """
269

270
def remove_user_from_group(user_group_id, user_id, **options):
271
    """Remove a user from a user group.
272
    
273
    Args:
274
        user_group_id (str): The ID of the user group
275
        user_id (str): The ID of the user to remove
276
        **options: Additional API options
277
    
278
    Returns:
279
        dict: Updated group membership containing:
280
            - users (list): Current list of users in the group
281
    """
282

283
def user_group_users(user_group_id, **options):
284
    """Get all users in a specific user group.
285
    
286
    Args:
287
        user_group_id (str): The ID of the user group
288
        **options: Additional API options
289
    
290
    Returns:
291
        dict: Group members containing:
292
            - users (list): Array of user objects in the group
293
            - total_count (int): Number of users in the group
294
    """
295

296
def user_in_user_groups(user_id, **options):
297
    """Get all user groups that a user belongs to.
298
    
299
    Args:
300
        user_id (str): The ID of the user
301
        **options: Additional API options
302
    
303
    Returns:
304
        dict: User's group memberships containing:
305
            - user_groups (list): Array of group objects the user belongs to
306
            - total_count (int): Number of groups the user belongs to
307
    """
308
```
309

310
### Access Key Management
311

312
Generate and manage API access keys for sub-accounts.
313

314
```python { .api }
315
def access_keys(sub_account_id, page_size=None, page=None, sort_by=None, sort_order=None, **options):
316
    """Get access keys for a sub-account.
317
    
318
    Args:
319
        sub_account_id (str): The ID of the sub-account
320
        page_size (int, optional): Number of entries per page
321
        page (int, optional): Page number to retrieve (max 100 pages)
322
        sort_by (str, optional): Sort field. Options:
323
            - 'api_key': Sort by API key value
324
            - 'created_at': Sort by creation date
325
            - 'name': Sort by access key name
326
            - 'enabled': Sort by enabled status
327
        sort_order (str, optional): Sort direction ('asc' or 'desc', default: 'desc')
328
        **options: Additional API options
329
    
330
    Returns:
331
        dict: Access keys list containing:
332
            - access_keys (list): Array of access key objects
333
            - total_count (int): Total number of access keys
334
    """
335

336
def generate_access_key(sub_account_id, name=None, enabled=None, **options):
337
    """Generate a new access key for a sub-account.
338
    
339
    Args:
340
        sub_account_id (str): The ID of the sub-account
341
        name (str, optional): Descriptive name for the access key
342
        enabled (bool, optional): Whether the key should be enabled (default: True)
343
        **options: Additional API options
344
    
345
    Returns:
346
        dict: Generated access key details containing:
347
            - api_key (str): The generated API key
348
            - api_secret (str): The generated API secret
349
            - name (str): Access key name
350
            - enabled (bool): Key status
351
            - created_at (str): Creation timestamp
352
    """
353

354
def update_access_key(sub_account_id, api_key, name=None, enabled=None, dedicated_for=None, **options):
355
    """Update an existing access key.
356
    
357
    Args:
358
        sub_account_id (str): The ID of the sub-account
359
        api_key (str|int): The API key identifier to update
360
        name (str, optional): New descriptive name
361
        enabled (bool, optional): Enable or disable the key
362
        dedicated_for (str, optional): Designate key for specific purpose.
363
            Options: 'webhooks'
364
        **options: Additional API options
365
    
366
    Returns:
367
        dict: Updated access key details
368
    """
369

370
def delete_access_key(sub_account_id, api_key=None, name=None, **options):
371
    """Delete an access key by API key or name.
372
    
373
    Args:
374
        sub_account_id (str): The ID of the sub-account
375
        api_key (str|int, optional): The API key to delete
376
        name (str, optional): The name of the access key to delete
377
        **options: Additional API options
378
    
379
    Note:
380
        Either api_key or name must be provided
381
    
382
    Returns:
383
        dict: Deletion result containing:
384
            - message (str): Operation status
385
    """
386
```
387

388
### Configuration Management
389

390
Configure provisioning API credentials and settings.
391

392
```python { .api }
393
class AccountConfig:
394
    """Configuration class for Cloudinary Provisioning API."""
395
    
396
    def __init__(self):
397
        """Initialize account configuration.
398
        
399
        Automatically loads configuration from:
400
        - CLOUDINARY_ACCOUNT_URL environment variable (format: account://key:secret@account_id)
401
        - Django settings (if available)
402
        """
403

404
def account_config(**keywords):
405
    """Configure provisioning API credentials.
406
    
407
    Args:
408
        account_id (str, optional): Cloudinary account identifier
409
        provisioning_api_key (str, optional): Provisioning API key
410
        provisioning_api_secret (str, optional): Provisioning API secret
411
        **keywords: Additional configuration parameters
412
    
413
    Returns:
414
        AccountConfig: Updated configuration instance
415
    
416
    Example:
417
        account_config(
418
            account_id="your_account_id",
419
            provisioning_api_key="your_api_key",
420
            provisioning_api_secret="your_api_secret"
421
        )
422
    """
423

424
def reset_config():
425
    """Reset configuration to default state.
426
    
427
    Clears all manually set configuration and reloads from environment variables.
428
    """
429
```
430

431
### User Roles
432

433
Available user roles for role-based access control.
434

435
```python { .api }
436
class Role:
437
    """Predefined user roles for access control."""
438
    
439
    MASTER_ADMIN = "master_admin"
440
    """Full administrative access across all accounts and sub-accounts."""
441
    
442
    ADMIN = "admin"  
443
    """Administrative access to assigned sub-accounts."""
444
    
445
    BILLING = "billing"
446
    """Access to billing information and usage reports."""
447
    
448
    TECHNICAL_ADMIN = "technical_admin"
449
    """Technical configuration access for assigned sub-accounts."""
450
    
451
    REPORTS = "reports"
452
    """Read-only access to reports and analytics."""
453
    
454
    MEDIA_LIBRARY_ADMIN = "media_library_admin"
455
    """Administrative access to Media Library features."""
456
    
457
    MEDIA_LIBRARY_USER = "media_library_user"
458
    """User-level access to Media Library features."""
459
```
460

461
## Configuration Setup
462

463
### Environment Variables
464

465
Configure the Provisioning API using environment variables:
466

467
```bash
468
# Set the account URL with credentials
469
export CLOUDINARY_ACCOUNT_URL="account://api_key:api_secret@account_id"
470
```
471

472
### Programmatic Configuration
473

474
Configure credentials in your application:
475

476
```python
477
import cloudinary.provisioning
478

479
# Configure using individual parameters
480
cloudinary.provisioning.account_config(
481
    account_id="your_account_id",
482
    provisioning_api_key="your_provisioning_key", 
483
    provisioning_api_secret="your_provisioning_secret"
484
)
485

486
# Or reset to reload from environment
487
cloudinary.provisioning.reset_config()
488
```
489

490
## Usage Examples
491

492
### Complete Sub-Account Setup
493

494
```python
495
import cloudinary.provisioning
496
from cloudinary.provisioning import Role
497

498
# Create a new sub-account
499
sub_account = cloudinary.provisioning.create_sub_account(
500
    name="Client Portal",
501
    cloud_name="client_portal_prod",
502
    enabled=True,
503
    custom_attributes={
504
        "client_id": "12345",
505
        "tier": "premium"
506
    }
507
)
508

509
# Create admin user for the sub-account
510
admin_user = cloudinary.provisioning.create_user(
511
    name="client_admin",
512
    email="admin@client.com", 
513
    role=Role.ADMIN,
514
    sub_account_ids=[sub_account['id']]
515
)
516

517
# Generate access keys for the sub-account
518
api_keys = cloudinary.provisioning.generate_access_key(
519
    sub_account_id=sub_account['id'],
520
    name="Production Keys",
521
    enabled=True
522
)
523
```
524

525
### User Group Management
526

527
```python
528
# Create a user group
529
dev_group = cloudinary.provisioning.create_user_group("Developers")
530

531
# Add users to the group
532
cloudinary.provisioning.add_user_to_group(
533
    user_group_id=dev_group['id'],
534
    user_id=admin_user['id']
535
)
536

537
# List all users in the group
538
group_members = cloudinary.provisioning.user_group_users(dev_group['id'])
539
```
540

541
### Access Key Rotation
542

543
```python
544
# List existing access keys
545
current_keys = cloudinary.provisioning.access_keys(
546
    sub_account_id="sub_account_123",
547
    sort_by="created_at",
548
    sort_order="desc"
549
)
550

551
# Generate new access key
552
new_key = cloudinary.provisioning.generate_access_key(
553
    sub_account_id="sub_account_123", 
554
    name="Rotated Production Key"
555
)
556

557
# Disable old access key
558
cloudinary.provisioning.update_access_key(
559
    sub_account_id="sub_account_123",
560
    api_key=current_keys['access_keys'][0]['api_key'],
561
    enabled=False
562
)
563
```