Storage

The Storage settings page lets you connect a private S3-compatible bucket — AWS S3, Cloudflare R2, Backblaze B2, Wasabi, or any MinIO-compatible endpoint. Once verified, all new file uploads go directly to your bucket instead of the shared platform bucket. A one-time migration copies your existing files over.

Note

Your access key and secret are encrypted with AES-256-GCM before being stored. They are never shown in plain text after the first save, and the platform only uses them to generate short-lived pre-signed URLs — your credentials are never sent to the browser.

---

Status badge

Badge	Meaning
Platform default	No custom bucket configured. Files go to the shared platform bucket.
Verified	Custom bucket is configured and the connection test passed. All new uploads go to your bucket.
Not Verified	A bucket is saved but the connection test has not been completed or has failed.

---

Supported providers

Provider	Notes
AWS S3	Use a regional endpoint such as https://s3.us-east-1.amazonaws.com.
Cloudflare R2	Endpoint is https://<account-id>.r2.cloudflarestorage.com. R2 has no egress fees.
Backblaze B2	Use the S3-compatible endpoint for your region, e.g. https://s3.us-west-004.backblazeb2.com.
Wasabi	Endpoint is https://s3.wasabisys.com (or a regional variant).
Custom / MinIO	Any S3-compatible endpoint. Enter the full URL including the scheme.

---

Setting up your bucket

1. Create a bucket in your storage provider’s console. Give it a private (non-public) access policy — the platform accesses files through pre-signed URLs, not public reads.

2. Create an IAM user or API key with the following permissions on that bucket:

   • s3:GetObject
   • s3:PutObject
   • s3:DeleteObject
   • s3:ListBucket
   • s3:HeadBucket

3. Configure CORS on the bucket so that the browser can complete the upload verification step. The allowed origin must include your school’s app domain. If you skip this step, the connection test will fail at step 3 and the AI-assisted CORS fix guide will open automatically.

4. Enter the details on the Storage settings page:

   • Provider — select the matching card
   • Endpoint — the full S3-compatible URL (pre-filled for known providers)
   • Region — required for AWS; leave blank for providers that don’t use regions
   • Bucket — the exact bucket name
   • Access Key ID and Secret Access Key

5. Click Save, then Test Connection to verify the five-step connection check.

---

The 5-step connection test

When you click Test Connection, the platform runs five checks in order:

Step	What is checked	Runs on
1	Bucket exists (HeadBucket)	Server
2	Credentials have write permission (PutObject on a test file)	Server
3	Browser can upload via a pre-signed URL (CORS verification)	Browser
4	Browser can download via a pre-signed URL (CORS verification)	Browser
5	Cleanup — test file deleted, bucket marked Verified	Server

Steps 3 and 4 run directly from your browser against your bucket. If either fails due to a CORS error, a Get CORS fix guide button appears. Clicking it opens a drawer with an AI-generated, provider-specific set of CORS configuration instructions streamed in real time.

---

CORS fix guide

When the browser-side test steps fail, the platform detects your provider and streams a tailored fix guide. The guide tells you exactly which CORS rules to add and where to add them in your provider’s console. Follow the steps, save the CORS policy, then click Retry to re-run the test from step 3.

---

Migrating existing files

After your bucket is verified for the first time, a Migrate existing files panel appears. This one-time migration copies all files that were previously uploaded to the shared platform bucket into your new bucket.

Migration status	Meaning
Not started	Migration has not been initiated.
In progress	Files are being copied. A real-time progress bar shows the count.
Completed	All files copied successfully.
Failed	One or more files could not be copied. The failed count is shown. You can retry.

Caution

The migration copies files — it does not delete the originals from the platform bucket. After confirming all files are accessible from your bucket, you may remove the platform copies from your old bucket if you have direct access to it.

---

Storage usage

The Storage Usage row shows the total number of files and total size stored in your bucket, broken down by category (profile photos, class files, documents, etc.). Click the row to expand the full per-category breakdown.

Note

Usage figures are read directly from your bucket at the time you open the settings page. They reflect the actual contents of the bucket, not a cached count.

---

Removing your custom bucket

Click Remove storage config at the bottom of the page and confirm. This deletes your saved configuration (bucket name, credentials, and verification status). New uploads will revert to the shared platform bucket immediately. Files already in your bucket are not deleted — they remain accessible as long as the pre-signed URLs generated before removal are still valid.

---

Permissions

The Storage settings page requires the AI Config Manage permission (ai_config:manage). This is the same permission used for the AI Assistant settings page. It is held by owners, managers, and any staff position explicitly granted the permission.

---

Troubleshooting

”HeadBucket failed — bucket not found or credentials invalid”

Check that the bucket name matches exactly (case-sensitive) and that the access key ID and secret are correct. Make sure the IAM user has at least s3:HeadBucket on the bucket.

”Upload test failed (step 3) — CORS error”

Your bucket is blocking browser uploads. Use the Get CORS fix guide button to get provider-specific instructions. The most common fix is adding an AllowedOrigin rule that includes your school’s app domain.

”Download test failed (step 4) — CORS error”

Same cause as above — the CORS policy is missing GET in AllowedMethods or is missing the correct origin. The fix guide covers both.

”I saved new credentials but the status shows Not Verified”

Changing the endpoint, region, bucket name, or credentials invalidates the previous verification. Re-run the connection test to verify again.

”The migration shows some failed files”

Failed files are usually caused by transient network errors or bucket permission issues at copy time. Check that the IAM policy includes s3:PutObject and retry the migration. Files that succeeded on a previous run are not re-copied.