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 "file=@invoice.pdf"

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 is h (hours), d (days), or m (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