Appearance
Files & S3 Storage
TiruPay can store and serve files on your behalf using S3-compatible object storage. A File object represents an uploaded file and holds its metadata alongside a reference to where the binary data lives in S3. Files are used for invoices, service logos, terms of service documents, images, and other attachments.
File Object
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier |
filename | string | Original filename |
content_type | string | MIME type (e.g. image/png, application/pdf) |
size | integer | File size in bytes |
category | enum | What kind of file this is (see Categories) |
blur_hash | string | null | BlurHash preview string, computed automatically for images under 5 MB |
width | integer | null | Width in pixels, if the file is an image |
height | integer | null | Height in pixels, if the file is an image |
focus_x | number | null | Relative horizontal focus point (0-1) used when cropping generated variants. Defaults to the image's center if not set |
focus_y | number | null | Relative vertical focus point (0-1) used when cropping generated variants. Defaults to the image's center if not set |
s3_key | string | The S3 object key |
bucket | string | The S3 bucket the file lives in |
service_id | string | The service this file belongs to |
uploaded_by | string | null | ID of the user who uploaded the file |
s3_configuration_id | string | null | The S3 configuration used for this file (null = default configuration) |
deleted_at | datetime | null | When the file was deleted from S3 (null = still present) |
created_at | datetime | When the file record was created |
updated_at | datetime | When the file record was last updated |
FilePublicLite vs FilePublic
Unauthenticated and regular user requests receive a reduced FilePublicLite response without s3_key, bucket, uploaded_by, service_id, and s3_configuration_id. Admins and service accounts receive the full FilePublic object.
Categories
The category determines what the file is used for and who can access it.
| Category | Description | Who can access |
|---|---|---|
image | Images (e.g. service logos, product photos) | Everyone (unauthenticated) |
legal_document | Legal document versions (e.g. Terms of Service) | Everyone, but only once the version is FINALIZED, PUBLISHED, or ARCHIVED. Admins always see all versions including DRAFT. |
invoice | Invoice PDFs generated by TiruPay | Admins, Services, Users linked to the invoice's customer |
article_document | Article Document version files (e.g. purchasable manuals) | Admins, Services, Users linked to a customer holding a grant for that specific version |
mail | Files attached to emails | Admins and Services only |
tax | Tax export files | Admins and Services only |
other | General attachments | Admins and Services only |
BlurHash for images
TiruPay automatically computes a BlurHash for uploaded images smaller than 5 MB. Use the blur_hash field to render a lightweight placeholder before the full image loads.
Image Variants
For uploaded images smaller than 5 MB, TiruPay automatically generates a set of downscaled variants: one for every combination of aspect ratio and format below. Each variant is cropped around the file's focus point (focus_x/focus_y, defaulting to the image's center) so the relevant part of the image is not cut off.
| Aspect ratio | Formats |
|---|---|
1:1 | avif, webp, jpeg |
4:3 | avif, webp, jpeg |
4:5 | avif, webp, jpeg |
Request a specific variant instead of the original file by passing format and aspect_ratio to the download or stream endpoints. Both parameters must be given together.
Setting the focus point
Pass focus_x and focus_y (each 0-1) to POST /files/upload to control where variants are cropped around, e.g. to keep a face or logo centered in a wide source image. Omit them to crop around the image's center.
Variants are generated asynchronously
Variants are generated in the background alongside the BlurHash, so they may not exist yet immediately after upload. Requesting a variant that doesn't (yet) exist returns 404 Not Found.
S3 Configuration
By default, TiruPay stores files using a shared S3 configuration. Each service can optionally bring its own S3-compatible storage by configuring an S3Configuration.
| Field | Type | Description |
|---|---|---|
url | string | S3-compatible endpoint URL |
default_bucket | string | null | Default bucket for this service. TiruPay generates one automatically if not set |
access_key | string | S3 access key |
secret_key | string | S3 secret key |
When a file is uploaded, TiruPay picks the bucket in this order:
- The
bucketparameter passed to the upload endpoint (if provided) - The
default_bucketfrom the service'sS3Configuration - An auto-generated bucket name for the service
Changing S3 configuration after upload
Changing a service's S3 configuration after files have already been uploaded will break existing file links. All previously uploaded files remain on the old bucket. Migrate them manually before switching configurations.
Self-hosted storage is outside TiruPay' control
If a service brings its own S3Configuration, the underlying bucket and its contents are owned and managed by that service's infrastructure, not by TiruPay. TiruPay' delete protections (e.g. for invoice, legal_document, and article_document files still in use) only guard the official API path - they cannot prevent a service from deleting, moving, or modifying objects directly through its own S3 provider. Services using their own storage are responsible for the integrity of the underlying bucket.
Uploading Files
POST /files/upload?service_id={id}
Upload a file as multipart/form-data. The file is stored in S3 and a File record is created in the database.
| Parameter | Type | Description |
|---|---|---|
service_id | string | The service to associate the file with |
file | file | The file to upload (max 25 MB) |
category | enum | File category (default: other) |
bucket | string | null | Override the target bucket |
focus_x | number | null | Relative horizontal focus point (0-1) for cropping image variants. Defaults to center |
focus_y | number | null | Relative vertical focus point (0-1) for cropping image variants. Defaults to center |
25 MB limit
Files larger than 25 MB are rejected.
Downloading Files
GET /files/{file_id}/download
Redirects (307) to a presigned S3 URL for the file. This is the preferred way to download a file - only use /stream below if your setup can't follow the redirect to S3 directly.
GET /files/{file_id}/stream
Proxies the file content through the TiruPay API server instead of redirecting to S3. The response includes a Content-Disposition: attachment header with the original filename. The optional chunk_size query parameter controls the streaming chunk size (max 52 000 bytes, default 8 192).
Both endpoints accept the same parameters:
| Parameter | Type | Description |
|---|---|---|
format | enum | null | Format of an image variant to fetch instead of the original file (avif, webp, jpeg) |
aspect_ratio | enum | null | Aspect ratio of an image variant to fetch instead of the original file (1:1, 4:3, 4:5) |
format and aspect_ratio must be given together, or omitted together (400 Bad Request otherwise). Returns 404 Not Found if no variant exists for the given combination.
Returns 410 Gone if the file has been deleted from S3 (i.e. deleted_at is set).
Deleting Files
DELETE /files/{file_id}
Deletes the binary data from S3 and sets deleted_at on the file record. The file object itself is never removed from the database — it is kept for audit and reference purposes (e.g. invoice records that reference the file remain intact). Any generated image variants are removed entirely, both their binary data and their records.
Invoices cannot be deleted
Files with category invoice are protected and cannot be deleted through the API.
Legal and Article Documents cannot be deleted while in use
A legal_document file cannot be deleted while it is linked to any Document version. An article_document file cannot be deleted while it is linked to any Article Document version - customers may hold an active grant against it. Detach or supersede the version first.
Viewing and Downloading
Access is determined by the file's category (see Categories above). The same rules apply to the metadata endpoint (GET /files/{id}) and both download endpoints (GET /files/{id}/download, GET /files/{id}/stream), for the original file and any of its variants.
404 instead of 403
To prevent enumeration attacks, requests for inaccessible files return 404 Not Found rather than 403 Forbidden.
Uploading and deleting requires Admin
Only Admin accounts can upload (POST /files/upload) or delete (DELETE /files/{id}) files, and only within the services they have access to. Service accounts can view and download files but not upload or delete them.
Relationships
- Services - Every file belongs to a service. A service can optionally provide its own S3 configuration.
- Invoicing - Invoice PDFs are stored as
invoice-category files. Users gain access to them through the customer linked to the invoice. - Legal Documents - Document version content is stored as
legal_document-category files. - Article Documents - Purchasable document version content is stored as
article_document-category files. Users gain access through aCustomerDocumentGrant. - Users - The
uploaded_byfield records which user uploaded the file. Users can accessinvoicefiles if they are linked to the corresponding customer.