Step-by-step guide for uploading files using the pre-signed URL pattern.
This guide explains how to upload files using the Files API's pre-signed URL pattern. The upload process consists of two steps: getting a pre-signed URL from the API, then uploading directly to S3 storage.
Overview
The file upload process is designed for security and scalability:
- API Request: Get a pre-signed URL and upload parameters
- Direct Upload: Upload file directly to S3 using the provided URL
- Verification: File is automatically processed and available for use
Step 1: Get Upload URL
First, request a pre-signed URL from the API with your file metadata:
Request
curl -X POST https://api.authvia.com/v3/accounts/{account-id}/files \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"fileName": "invoice_2024_001.pdf",
"contentType": "application/pdf",
"description": "Invoice for customer CUST001",
"businessProcess": "payment-processing",
"businessProcessAction": "document-upload",
"expiration": "30d"
}'Required Fields
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
fileName | string | ✅ | Name of the file to upload | invoice.pdf |
contentType | string | ✅ | MIME type of the file | application/pdf |
Optional Fields
| Field | Type | Description | Example |
|---|---|---|---|
description | string | Human-readable description | Invoice for customer CUST001 |
businessProcess | string | Associated business process | payment-processing |
businessProcessAction | string | Specific action within process | document-upload |
expiration | string | File expiration time | 30d, 5h, 60m |
Response
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"uploadUrl": "https://s3.amazonaws.com/bucket/presigned-url",
"fields": {
"key": "files/550e8400-e29b-41d4-a716-446655440000",
"bucket": "authvia-files",
"X-Amz-Algorithm": "AWS4-HMAC-SHA256",
"X-Amz-Credential": "AKIA...",
"X-Amz-Date": "20240115T103000Z",
"Policy": "eyJleHBpcmF0aW9uIjoiMjAyNC0wMS0xNVQxMDozNTowMFoiLCJjb25kaXRpb25zIjpbeyJidWNrZXQiOiJhdXRodmlhLWZpbGVzIn0sWyJzdGFydHMtd2l0aCIsIiRrZXkiLCJmaWxlcy8iXV19",
"X-Amz-Signature": "abc123..."
}
}Step 2: Upload to S3
Use the pre-signed URL and fields to upload your file directly to S3:
Using cURL
curl -X POST "https://s3.amazonaws.com/bucket/presigned-url" \
-F "key=files/550e8400-e29b-41d4-a716-446655440000" \
-F "bucket=authvia-files" \
-F "X-Amz-Algorithm=AWS4-HMAC-SHA256" \
-F "X-Amz-Credential=AKIA..." \
-F "X-Amz-Date=20240115T103000Z" \
-F "Policy=eyJleHBpcmF0aW9uIjoiMjAyNC0wMS0xNVQxMDozNTowMFoiLCJjb25kaXRpb25zIjpbeyJidWNrZXQiOiJhdXRodmlhLWZpbGVzIn0sWyJzdGFydHMtd2l0aCIsIiRrZXkiLCJmaWxlcy8iXV19" \
-F "X-Amz-Signature=abc123..." \
-F "[email protected]"Content Type Validation
The API enforces strict content type validation. File extensions must match the content type:
| Content Type | Valid Extensions | Example |
|---|---|---|
application/pdf | .pdf | invoice.pdf |
text/plain | .txt, .text | report.txt |
image/png | .png | logo.png |
image/jpeg | .jpg, .jpeg | photo.jpg |
image/webp | .webp | image.webp |
image/bmp | .bmp | image.bmp |
image/tiff | .tiff, .tif | scan.tiff |
Important: If the file extension doesn't match the content type, the API will return a validation error.
File Expiration
Files can have configurable expiration times:
- Format:
{number}{unit}where unit ish(hours),d(days), orm(minutes) - Default:
60d(60 days) if not specified - Examples:
5h,10d,30m
{
"fileName": "temporary_report.pdf",
"contentType": "application/pdf",
"expiration": "5h" // Expires in 5 hours
}Error Handling
Common Errors
| Error Code | Description | Resolution |
|---|---|---|
INVALID_CONTENT_TYPE | Content type doesn't match file extension | Ensure file extension matches content type |
FILE_TOO_LARGE | File exceeds size limit | Reduce file size or contact support |
INVALID_EXPIRATION | Invalid expiration format | Use format like 30d, 5h, 60m |
MISSING_FIELDS | Required fields missing | Include fileName and contentType |
UNAUTHORIZED | Invalid or missing authentication | Check your API token |
FORBIDDEN | Insufficient permissions | Verify account access |
S3 Upload Errors
| Error | Description | Resolution |
|---|---|---|
Access Denied | Pre-signed URL expired or invalid | Get a new upload URL |
Entity Too Large | File exceeds S3 limits | Reduce file size |
Network Error | Connection issues | Retry the upload |