Scopix

Documentation

Custom Storage

Configure organization-level settings including custom S3 storage

Admin Access Required

Settings operations require admin permissions on the tenant. Ensure your API key has the appropriate role.

Custom S3 Storage (BYOB)

Bring Your Own Bucket (BYOB) lets you store uploaded files in your own AWS S3 bucket instead of Scopix's default storage. You maintain full control over your data.

Required IAM Permissions

Your IAM user/role needs these S3 permissions:

  • s3:PutObject - Upload files
  • s3:GetObject - Download files
  • s3:HeadBucket - Validate bucket access

Configure Custom S3 Bucket

Set up your S3 bucket for file storage (one-time setup)

python
async with Scopix(api_key="scopix_...") as client:
    # Configure your S3 bucket
    status = await client.settings.configure_custom_s3(
        access_key_id="AKIAIOSFODNN7EXAMPLE",
        secret_access_key="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
        bucket_name="my-company-uploads",
        region="us-east-1"
    )


    print(f"Configured: {status.configured}")
    print(f"Bucket: {status.bucket_name}")
    print(f"Region: {status.region}")

Check Configuration Status

Get current S3 configuration without exposing credentials

python
# Check if custom S3 is configured
status = await client.settings.get_custom_s3_status()


if status.configured:
    print(f"Bucket: {status.bucket_name}")
    print(f"Region: {status.region}")
    print(f"Configured at: {status.configured_at}")
    print(f"Validated: {status.is_validated}")
else:
    print("No custom S3 configured")

Validate Credentials

Test that stored credentials still have bucket access

python
# Validate credentials are still working
result = await client.settings.validate_custom_s3()


if result.valid:
    print(f"Bucket {result.bucket_name} is accessible")
else:
    print(f"Validation failed: {result.error}")

Remove Configuration

Remove custom S3 to use Scopix's default storage

python
# Remove custom S3 configuration
result = await client.settings.remove_custom_s3()
print(result["message"])  # "Custom S3 configuration removed"

Using Custom Storage for Uploads

Once configured, specify storage_target to choose where files are stored.

Upload to Custom Bucket

python
# Upload to your S3 bucket
result = await client.files.upload_batch(
    "photo.jpg",
    storage_target="custom"
)


# Upload to Scopix's default bucket
result = await client.files.upload_batch(
    "photo.jpg",
    storage_target="default"  # Or omit for default
)


# Batch upload to custom bucket
results = await client.files.upload_batch(
    ["img1.jpg", "img2.jpg", "img3.jpg"],
    storage_target="custom"
)

S3ConfigStatus Type

Configuration status returned by settings methods

python
@dataclass
class S3ConfigStatus:
    configured: bool           # Whether custom S3 is configured
    bucket_name: Optional[str] # Configured bucket name
    region: Optional[str]      # AWS region
    configured_at: Optional[str]  # ISO timestamp
    is_validated: Optional[bool]  # Whether credentials were validated
    error: Optional[str]       # Error message if failed


@dataclass
class S3ValidationResult:
    valid: bool                # Whether credentials work
    bucket_name: Optional[str] # Bucket name if valid
    region: Optional[str]      # Region if valid
    error: Optional[str]       # Error message if invalid

Security

  • Credentials are encrypted at rest
  • Secret access keys are never returned in API responses
  • Credentials are validated via head_bucket before storage
  • Files upload directly to your bucket via presigned URLs

Related

Uploading Images

Upload images with storage_target option

Settings Resource Reference

SDK methods for S3 configuration

Client Configuration

Configure the SDK client