Concepts
Organizations, apps, files, and where to put API keys
Organizations
An organization owns apps, members, usage quotas, and API keys. Keys never switch orgs.
Apps
An app is a container for files (slug + name). Uploads require an appId. Create apps in the portal or via the SDK (oleqfiles.apps / oleqFiles.Apps).
Each app has an environment:
- sandbox — for development and testing (
sk_test_…keys) - production — for live workloads (
sk_live_…keys)
Promote a sandbox app to production when you are ready (one-way, via portal or SDK).
Files
Each file has an id (S3 object key). Callers store that id. Confirmed uploads also get a public src URL (CDN).
Typical upload flow (the SDK upload helper does this for you):
POST /api/uploads— presign (needs SHA-256 checksum)PUTto the presigned URL (withx-amz-checksum-sha256)POST /api/uploads/complete— confirm and record usage
You can perform those steps with any HTTP client — see HTTP API.
Retention
Incomplete uploads
If you presign but never call POST /api/uploads/complete, the pending file is deleted automatically after 15 minutes (S3 object and DB row). Complete within that window even if the presigned PUT URL has already expired (presign TTL is 2 minutes).
Sandbox environment
Files uploaded to sandbox apps are stored under a dev/ key prefix and are deleted automatically after 7 days, confirmed or not. Cleanup runs once daily at midnight EAT (UTC+3). Do not use sandbox for long-lived assets; use production apps for permanent files.
Where to put the key
| Layer | Use API key? |
|---|---|
| Your backend / worker / Nest / ASP.NET | Yes |
| Next.js Route Handlers / Server Actions | Yes (server only) |
| Browser / mobile client talking straight to OleqFiles | No — proxy through your backend |
End users talk to your app; your app talks to OleqFiles.