Provisioning API

def sub_accounts(enabled=None, ids=None, prefix=None, **options):
    """List all sub-accounts.
    
    Args:
        enabled (bool, optional): Filter by enabled status. 
            True for enabled accounts, False for disabled, None for all
        ids (list, optional): List of specific sub-account IDs to retrieve (up to 100).
            When provided, other filters are ignored
        prefix (str, optional): Search by sub-account name prefix (case-insensitive)
        **options: Additional API options
    
    Returns:
        dict: Sub-accounts list containing:
            - sub_accounts (list): Array of sub-account objects
            - total_count (int): Total number of matching sub-accounts
    """

def create_sub_account(name, cloud_name=None, custom_attributes=None, enabled=None, base_account=None, **options):
    """Create a new sub-account.
    
    Args:
        name (str): Display name for the new sub-account
        cloud_name (str, optional): Unique cloud name (alphanumeric and underscores only).
            Must be unique across all Cloudinary accounts
        custom_attributes (dict, optional): Custom key-value attributes to associate
        enabled (bool, optional): Whether to create as enabled (default: True)
        base_account (str, optional): ID of existing sub-account to copy settings from
        **options: Additional API options
    
    Returns:
        dict: Created sub-account details containing:
            - id (str): Unique sub-account identifier
            - name (str): Display name
            - cloud_name (str): Cloud name for API access
            - enabled (bool): Account status
            - created_at (str): Creation timestamp
            - custom_attributes (dict): Custom attributes
    """

def sub_account(sub_account_id, **options):
    """Get details of a specific sub-account.
    
    Args:
        sub_account_id (str): The ID of the sub-account to retrieve
        **options: Additional API options
    
    Returns:
        dict: Sub-account details with all properties
    """

def update_sub_account(sub_account_id, name=None, cloud_name=None, custom_attributes=None, enabled=None, **options):
    """Update an existing sub-account.
    
    Args:
        sub_account_id (str): The ID of the sub-account to update
        name (str, optional): New display name
        cloud_name (str, optional): New cloud name (must be unique)
        custom_attributes (dict, optional): Updated custom attributes
        enabled (bool, optional): Enable or disable the account
        **options: Additional API options
    
    Returns:
        dict: Updated sub-account details
    """

def delete_sub_account(sub_account_id, **options):
    """Delete a sub-account permanently.
    
    Args:
        sub_account_id (str): The ID of the sub-account to delete
        **options: Additional API options
    
    Returns:
        dict: Deletion result containing:
            - message (str): Confirmation message
    """

def users(user_ids=None, sub_account_id=None, pending=None, prefix=None, last_login=None, from_date=None, to_date=None, **options):
    """List users with filtering options.
    
    Args:
        user_ids (list, optional): Specific user IDs to retrieve
        sub_account_id (str, optional): Filter by users with access to this sub-account
        pending (bool, optional): Filter by pending status.
            True for pending users, False for confirmed, None for all
        prefix (str, optional): Filter by username prefix
        last_login (bool, optional): Filter by last login date range.
            True for users who logged in during date range, False for those who didn't
        from_date (datetime, optional): Start date for last_login filter
        to_date (datetime, optional): End date for last_login filter
        **options: Additional API options
    
    Returns:
        dict: Users list containing:
            - users (list): Array of user objects
            - total_count (int): Total number of matching users
    """

def create_user(name, email, role, sub_account_ids=None, **options):
    """Create a new user account.
    
    Args:
        name (str): Username for the new user
        email (str): Email address (must be unique)
        role (str): User role. Use Role class constants:
            - Role.MASTER_ADMIN: Full access across all accounts
            - Role.ADMIN: Administrative access to assigned sub-accounts
            - Role.BILLING: Billing and usage access
            - Role.TECHNICAL_ADMIN: Technical configuration access
            - Role.REPORTS: Read-only reporting access
            - Role.MEDIA_LIBRARY_ADMIN: Media library management
            - Role.MEDIA_LIBRARY_USER: Media library user access
        sub_account_ids (list, optional): Sub-accounts this user can access.
            Ignored if role is master_admin
        **options: Additional API options
    
    Returns:
        dict: Created user details containing:
            - id (str): Unique user identifier
            - name (str): Username
            - email (str): Email address
            - role (str): Assigned role
            - enabled (bool): Account status
            - sub_account_ids (list): Accessible sub-accounts
            - created_at (str): Creation timestamp
    """

def user(user_id, **options):
    """Get details of a specific user.
    
    Args:
        user_id (str): The ID of the user to retrieve
        **options: Additional API options
    
    Returns:
        dict: User details with all properties
    """

def update_user(user_id, name=None, email=None, role=None, sub_account_ids=None, **options):
    """Update an existing user account.
    
    Args:
        user_id (str): The ID of the user to update
        name (str, optional): New username
        email (str, optional): New email address
        role (str, optional): New role (use Role class constants)
        sub_account_ids (list, optional): Updated list of accessible sub-accounts.
            Ignored if role is master_admin
        **options: Additional API options
    
    Returns:
        dict: Updated user details
    """

def delete_user(user_id, **options):
    """Delete a user account permanently.
    
    Args:
        user_id (str): The ID of the user to delete
        **options: Additional API options
    
    Returns:
        dict: Deletion result containing:
            - message (str): Confirmation message
    """

def user_groups(**options):
    """List all user groups.
    
    Args:
        **options: Additional API options
    
    Returns:
        dict: User groups list containing:
            - user_groups (list): Array of user group objects
            - total_count (int): Total number of groups
    """

def create_user_group(name, **options):
    """Create a new user group.
    
    Args:
        name (str): Name for the new user group
        **options: Additional API options
    
    Returns:
        dict: Created user group details containing:
            - id (str): Unique group identifier
            - name (str): Group name
            - users_count (int): Number of users in the group
            - created_at (str): Creation timestamp
    """

def user_group(user_group_id, **options):
    """Get details of a specific user group.
    
    Args:
        user_group_id (str): The ID of the user group to retrieve
        **options: Additional API options
    
    Returns:
        dict: User group details with all properties
    """

def update_user_group(user_group_id, name, **options):
    """Update an existing user group.
    
    Args:
        user_group_id (str): The ID of the user group to update
        name (str): New group name
        **options: Additional API options
    
    Returns:
        dict: Updated user group details
    """

def delete_user_group(user_group_id, **options):
    """Delete a user group permanently.
    
    Args:
        user_group_id (str): The ID of the user group to delete
        **options: Additional API options
    
    Returns:
        dict: Deletion result containing:
            - message (str): Confirmation message
    """

def add_user_to_group(user_group_id, user_id, **options):
    """Add a user to a user group.
    
    Args:
        user_group_id (str): The ID of the user group
        user_id (str): The ID of the user to add
        **options: Additional API options
    
    Returns:
        dict: Updated group membership containing:
            - users (list): Current list of users in the group
    """

def remove_user_from_group(user_group_id, user_id, **options):
    """Remove a user from a user group.
    
    Args:
        user_group_id (str): The ID of the user group
        user_id (str): The ID of the user to remove
        **options: Additional API options
    
    Returns:
        dict: Updated group membership containing:
            - users (list): Current list of users in the group
    """

def user_group_users(user_group_id, **options):
    """Get all users in a specific user group.
    
    Args:
        user_group_id (str): The ID of the user group
        **options: Additional API options
    
    Returns:
        dict: Group members containing:
            - users (list): Array of user objects in the group
            - total_count (int): Number of users in the group
    """

def user_in_user_groups(user_id, **options):
    """Get all user groups that a user belongs to.
    
    Args:
        user_id (str): The ID of the user
        **options: Additional API options
    
    Returns:
        dict: User's group memberships containing:
            - user_groups (list): Array of group objects the user belongs to
            - total_count (int): Number of groups the user belongs to
    """

def access_keys(sub_account_id, page_size=None, page=None, sort_by=None, sort_order=None, **options):
    """Get access keys for a sub-account.
    
    Args:
        sub_account_id (str): The ID of the sub-account
        page_size (int, optional): Number of entries per page
        page (int, optional): Page number to retrieve (max 100 pages)
        sort_by (str, optional): Sort field. Options:
            - 'api_key': Sort by API key value
            - 'created_at': Sort by creation date
            - 'name': Sort by access key name
            - 'enabled': Sort by enabled status
        sort_order (str, optional): Sort direction ('asc' or 'desc', default: 'desc')
        **options: Additional API options
    
    Returns:
        dict: Access keys list containing:
            - access_keys (list): Array of access key objects
            - total_count (int): Total number of access keys
    """

def generate_access_key(sub_account_id, name=None, enabled=None, **options):
    """Generate a new access key for a sub-account.
    
    Args:
        sub_account_id (str): The ID of the sub-account
        name (str, optional): Descriptive name for the access key
        enabled (bool, optional): Whether the key should be enabled (default: True)
        **options: Additional API options
    
    Returns:
        dict: Generated access key details containing:
            - api_key (str): The generated API key
            - api_secret (str): The generated API secret
            - name (str): Access key name
            - enabled (bool): Key status
            - created_at (str): Creation timestamp
    """

def update_access_key(sub_account_id, api_key, name=None, enabled=None, dedicated_for=None, **options):
    """Update an existing access key.
    
    Args:
        sub_account_id (str): The ID of the sub-account
        api_key (str|int): The API key identifier to update
        name (str, optional): New descriptive name
        enabled (bool, optional): Enable or disable the key
        dedicated_for (str, optional): Designate key for specific purpose.
            Options: 'webhooks'
        **options: Additional API options
    
    Returns:
        dict: Updated access key details
    """

def delete_access_key(sub_account_id, api_key=None, name=None, **options):
    """Delete an access key by API key or name.
    
    Args:
        sub_account_id (str): The ID of the sub-account
        api_key (str|int, optional): The API key to delete
        name (str, optional): The name of the access key to delete
        **options: Additional API options
    
    Note:
        Either api_key or name must be provided
    
    Returns:
        dict: Deletion result containing:
            - message (str): Operation status
    """

class AccountConfig:
    """Configuration class for Cloudinary Provisioning API."""
    
    def __init__(self):
        """Initialize account configuration.
        
        Automatically loads configuration from:
        - CLOUDINARY_ACCOUNT_URL environment variable (format: account://key:secret@account_id)
        - Django settings (if available)
        """

def account_config(**keywords):
    """Configure provisioning API credentials.
    
    Args:
        account_id (str, optional): Cloudinary account identifier
        provisioning_api_key (str, optional): Provisioning API key
        provisioning_api_secret (str, optional): Provisioning API secret
        **keywords: Additional configuration parameters
    
    Returns:
        AccountConfig: Updated configuration instance
    
    Example:
        account_config(
            account_id="your_account_id",
            provisioning_api_key="your_api_key",
            provisioning_api_secret="your_api_secret"
        )
    """

def reset_config():
    """Reset configuration to default state.
    
    Clears all manually set configuration and reloads from environment variables.
    """

class Role:
    """Predefined user roles for access control."""
    
    MASTER_ADMIN = "master_admin"
    """Full administrative access across all accounts and sub-accounts."""
    
    ADMIN = "admin"  
    """Administrative access to assigned sub-accounts."""
    
    BILLING = "billing"
    """Access to billing information and usage reports."""
    
    TECHNICAL_ADMIN = "technical_admin"
    """Technical configuration access for assigned sub-accounts."""
    
    REPORTS = "reports"
    """Read-only access to reports and analytics."""
    
    MEDIA_LIBRARY_ADMIN = "media_library_admin"
    """Administrative access to Media Library features."""
    
    MEDIA_LIBRARY_USER = "media_library_user"
    """User-level access to Media Library features."""

# Set the account URL with credentials
export CLOUDINARY_ACCOUNT_URL="account://api_key:api_secret@account_id"

import cloudinary.provisioning

# Configure using individual parameters
cloudinary.provisioning.account_config(
    account_id="your_account_id",
    provisioning_api_key="your_provisioning_key", 
    provisioning_api_secret="your_provisioning_secret"
)

# Or reset to reload from environment
cloudinary.provisioning.reset_config()

import cloudinary.provisioning
from cloudinary.provisioning import Role

# Create a new sub-account
sub_account = cloudinary.provisioning.create_sub_account(
    name="Client Portal",
    cloud_name="client_portal_prod",
    enabled=True,
    custom_attributes={
        "client_id": "12345",
        "tier": "premium"
    }
)

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

# Generate access keys for the sub-account
api_keys = cloudinary.provisioning.generate_access_key(
    sub_account_id=sub_account['id'],
    name="Production Keys",
    enabled=True
)

# Create a user group
dev_group = cloudinary.provisioning.create_user_group("Developers")

# Add users to the group
cloudinary.provisioning.add_user_to_group(
    user_group_id=dev_group['id'],
    user_id=admin_user['id']
)

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

# List existing access keys
current_keys = cloudinary.provisioning.access_keys(
    sub_account_id="sub_account_123",
    sort_by="created_at",
    sort_order="desc"
)

# Generate new access key
new_key = cloudinary.provisioning.generate_access_key(
    sub_account_id="sub_account_123", 
    name="Rotated Production Key"
)

# Disable old access key
cloudinary.provisioning.update_access_key(
    sub_account_id="sub_account_123",
    api_key=current_keys['access_keys'][0]['api_key'],
    enabled=False
)