# Sigma REST API Scripts

A collection of Python scripts for managing Sigma Computing users and their access to Snowflake objects through the Sigma REST API.

## Features

- **Authentication**: Secure API client with automatic token refresh
- **User Management**: Create, update, and manage Sigma users
- **Object Listing**: List and organize Snowflake databases, schemas, and tables
- **Access Control**: Grant/revoke user access to Snowflake objects
- **Bulk Operations**: Perform access grants for multiple users and objects
- **Ownership Transfer**: Bulk transfer workbook/dashboard ownership between users
- **Configuration Management**: Flexible config system with environment variable support

## Setup

### 1. Install Dependencies

```bash
pip install requests
```

### 2. Configure API Access

#### Option A: Interactive Setup
```bash
python config.py
```

#### Option B: Environment Variables
```bash
export SIGMA_CLIENT_ID="your_client_id"
export SIGMA_CLIENT_SECRET="your_client_secret"
export SIGMA_BASE_URL="https://api.sigmacomputing.com"  # or your region
export SIGMA_SNOWFLAKE_CONNECTION="PROD_SIGMA_ORCHARD_SNOWFLAKE"  # optional
```

#### Option C: Configuration File
Create `sigma_config.json`:
```json
{
  "base_url": "https://api.sigmacomputing.com",
  "client_id": "your_client_id",
  "snowflake_connection_name": "PROD_SIGMA_ORCHARD_SNOWFLAKE"
}
```

### 3. Get API Credentials

1. In Sigma, go to **Administration** > **Developer Access**
2. Create a new API client
3. Copy the Client ID and Client Secret
4. Note your organization's base URL

## Usage Examples

### List Snowflake Objects
```bash
python examples/list_objects_example.py
```

### Grant Access to Users
```bash
python examples/grant_access_example.py
```

### Transfer Workbook Ownership

Bulk transfer ownership of workbooks/dashboards from one user to another:

```bash
# Preview what would be transferred (dry run)
python transfer_ownership.py --from old.owner@company.com --to new.owner@company.com --dry-run

# Transfer all workbooks
python transfer_ownership.py --from old.owner@company.com --to new.owner@company.com

# Transfer only workbooks in a specific folder
python transfer_ownership.py --from old.owner@company.com --to new.owner@company.com \
    --folder "Organization/Department/Content"

# Transfer workbooks with a specific name prefix
python transfer_ownership.py --from old.owner@company.com --to new.owner@company.com \
    --name "Content -"

# Test with a small batch first
python transfer_ownership.py --from old.owner@company.com --to new.owner@company.com --limit 2

# Skip confirmation prompt (for automation)
python transfer_ownership.py --from old.owner@company.com --to new.owner@company.com --yes

# With checkpoint for recovery and audit logging
python transfer_ownership.py --from old.owner@company.com --to new.owner@company.com \
    --checkpoint transfer.checkpoint.json --log-file transfer.log
```

### Custom Script Example
```python
from sigma_api_client import SigmaAPIClient
from snowflake_object_manager import SnowflakeObjectManager
from user_management import PermissionType
from config import ConfigManager

# Initialize
config = ConfigManager().get_sigma_config()
api_client = SigmaAPIClient(config)
manager = SnowflakeObjectManager(api_client)

# Grant database access
results = manager.grant_database_access(
    user_email="analyst@company.com",
    database_name="PROD",
    permission=PermissionType.VIEW
)

# Grant specific table access
result = manager.grant_table_access(
    user_email="analyst@company.com",
    database_name="PROD",
    schema_name="FACTS",
    table_name="SALES_DATA",
    permission=PermissionType.EXPLORE
)
```

## API Classes

### SigmaAPIClient
Base API client with authentication and rate limiting.

### UserManager
- `list_members()` - List all organization members
- `get_member_by_email(email)` - Find user by email
- `create_member(email, first_name, last_name, account_type)` - Create new user
- `update_member_account_type(member_id, account_type)` - Update user permissions

### PermissionManager
- `list_grants()` - List all access grants
- `grant_workbook_access()` - Grant workbook access
- `grant_workspace_access()` - Grant workspace access
- `revoke_access(grant_id)` - Remove access grant

### SnowflakeObjectManager
- `get_snowflake_objects()` - List all Snowflake databases, schemas, tables
- `grant_database_access()` - Grant access to entire database
- `grant_schema_access()` - Grant access to schema
- `grant_table_access()` - Grant access to specific table
- `bulk_grant_access()` - Grant access to multiple users/objects

### OwnershipManager
- `list_all_members()` - List all members with pagination
- `get_member_by_email(email)` - Find member by email
- `search_members_by_email(partial)` - Search members by partial email
- `list_files(type_filters)` - List all files/workbooks
- `list_files_by_owner(email, type_filters)` - List files owned by a user
- `transfer_ownership(inode_id, new_owner_id)` - Transfer single file ownership
- `bulk_transfer_ownership(files, new_owner_id)` - Bulk transfer with progress tracking

## Permission Types

- `VIEW` - Read-only access
- `EXPLORE` - Can explore and filter data
- `EDIT` - Can modify workbooks/datasets

## Base URLs by Region

- **US**: `https://api.sigmacomputing.com`
- **EU**: `https://api.eu.sigmacomputing.com`
- **Canada**: `https://api.ca.sigmacomputing.com`
- **UK**: `https://api.uk.sigmacomputing.com`
- **Australia**: `https://api.au.sigmacomputing.com`

## Security Notes

- Client secrets are never saved to configuration files
- Use environment variables for production deployments
- API tokens automatically refresh before expiration
- Rate limiting is implemented for token requests

## Error Handling

The scripts include comprehensive error handling:
- Invalid credentials
- Missing users or objects
- API rate limits
- Network issues

## File Structure

```
sigma-scripts/
├── sigma_api_client.py      # Base API client
├── user_management.py       # User and permission management
├── snowflake_object_manager.py  # Snowflake object access
├── transfer_ownership.py    # Bulk ownership transfer CLI
├── config.py               # Configuration management
├── examples/
│   ├── grant_access_example.py
│   └── list_objects_example.py
├── tests/
│   ├── test_config.py
│   ├── test_sigma_api_client.py
│   ├── test_user_management.py
│   ├── test_team_management.py
│   ├── test_snowflake_object_manager.py
│   └── test_transfer_ownership.py
└── README.md
```