SignStack handles various files securely and efficiently – from the PDF documents used in templates to user-uploaded signatures or supporting evidence. Our platform uses a centralized, modern approach that simplifies file handling for your application.

The fileId: Your Stable Reference 🆔

Instead of dealing with complex storage paths, SignStack assigns a unique, permanent fileId to every file uploaded to or generated by the system.

• Central Record: SignStack maintains a central record for each fileId, tracking essential information.

• Stable Reference: Throughout the SignStack platform (in Templates, Workflows, API responses), files are always referenced using this stable fileId. This means your application code uses a simple, predictable identifier, regardless of where or how the file is stored behind the scenes.

Secure & Scalable Transfers: Pre-Signed URLs 🔗

SignStack uses pre-signed URLs to handle file uploads and downloads directly between the client (like your user's browser or your server) and secure cloud storage (like Google Cloud Storage). This method bypasses your servers for the heavy lifting, providing significant benefits.

• How Uploads Work:

  1. Your application tells the SignStack API it wants to upload a file (POST /files/initiate-upload), providing the file's name and content hash (a SHA-256 fingerprint calculated client-side for data integrity).

  2. SignStack reserves a unique fileId, records the expected hash, and generates a secure, short-lived pre-signed URL specifically for uploading.

  3. Your application receives the uploadUrl and fileId. Your client then uploads the file directly to cloud storage using this URL.

  4. SignStack monitors the cloud storage and automatically marks the file as 'Available' once the upload completes successfully and the hash matches. (Your application doesn't need to send a separate confirmation).

• How Downloads Work:

  1. Your application requests a download URL for a specific fileId (GET /files/{fileId}/download-url).

  2. SignStack verifies permissions and generates a secure, short-lived pre-signed URL for reading the file.

  3. Your application receives the downloadUrl and the client fetches the file directly from cloud storage.

Benefits for Your Application

• Simplified Client Code: Your frontend or backend only needs to manage the fileId. You don't need to worry about complex storage paths or credentials.

• No Backend Proxying: Your servers do not need to handle large file uploads or downloads. By using pre-signed URLs, your clients interact directly with highly reliable and performant cloud storage. This saves you bandwidth, compute resources, and significantly simplifies your application architecture.

• Security & Integrity: Access is controlled via short-lived, permission-scoped URLs issued by SignStack. The mandatory client-side hashing ensures end-to-end data integrity, crucial for legal documents.

• Abstraction: The underlying storage (GCS, S3, etc.) is completely hidden. SignStack manages the infrastructure, providing you with a stable fileId-based API.

You manage files programmatically using the /files API endpoints.

➡️ Next: Core Concepts: Custom Functions