File Attachments API
Secure file attachments with client-side encryption, fully managed by our official SDKs.
📎 Overview
Our SDKs handle all the complexity of file encryption, upload, and retrieval. Files are encrypted client-side before transmission and stored securely on the server.
Official SDKs:
- CLI C# Tool - Cross-platform command-line interface
- JavaScript SDK - For Node.js and modern web applications
- JavaScript CDN - Simple browser integration
- Python SDK - Async Python client
📋 Attachment Limits
- Maximum attachments: 10 files per secret
- Total size limit: 10MB per secret (combined all attachments)
- Supported extensions: pdf, jpg, jpeg, png, docx, txt
- Storage duration: Files are stored for the same duration as the secret
🔐 Security Model
Client-Side Encryption
All SDKs automatically handle file encryption:
- Algorithm: AES-256-GCM with PBKDF2 key derivation
- Same encryption: Uses identical key material as secret content
- Individual encryption: Each file encrypted separately
- Zero Knowledge: Server never sees plaintext file content
📤 Upload Attachments
Create secrets with file attachments using the SDKs.
SDK Usage
bash
sharokey create "Secret with files" --hours 24 --views 1 --files document.pdf image.jpg1
javascript
const secret = await client.createSecret("Secret with files", {
hours: 24,
views: 1,
attachments: [
{ file: fileBuffer, name: "document.pdf" },
{ file: imageBuffer, name: "image.jpg" }
]
});1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
javascript
const secret = await Sharokey.create("Secret with files", 24, 1, {
attachments: [
{ file: fileData, name: "document.pdf" },
{ file: imageData, name: "image.jpg" }
]
});1
2
3
4
5
6
2
3
4
5
6
python
secret = await client.create("Secret with files",
hours=24,
views=1,
attachments=[
{"file": file_data, "name": "document.pdf"},
{"file": image_data, "name": "image.jpg"}
]
)1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
Response Format
json
{
"success": true,
"message": "Secret created successfully",
"data": {
"slug": "abc123def",
"description": "My secret document",
"message": "Please handle with care",
"expires_in_hours": 24,
"maximum_views": 5,
"current_views": 0,
"expiration": "2025-08-11T10:30:00Z",
"has_attachments": true,
"attachments_count": 2,
"share_url": "https://passlink.domaindev/abc123def#keyB_part_here",
"created_at": "2025-08-10T10:30:00Z"
}
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
📥 Retrieve Secrets with Attachments
Get secret metadata including attachment information.
SDK Usage
bash
sharokey get abc123def --details-only1
javascript
const details = await client.getSecretDetails("abc123def");1
javascript
const details = await Sharokey.getDetails("abc123def");1
python
details = await client.get_details("abc123def")1
Response Format
json
{
"success": true,
"data": {
"slug": "abc123def",
"description": "My secret document",
"creator": "[email protected]",
"maximum_views": 5,
"current_views": 0,
"expiration": "2025-08-11T18:52:37.000000Z",
"has_attachments": true,
"attachments": [
{
"name": "document.pdf"
},
{
"name": "image.jpg"
}
],
"is_expired": false,
"status": "active",
"share_url": "https://passlink.domaindev/abc123def",
"created_at": "2025-08-10T18:52:37.000000Z"
}
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
🚨 Error Responses
All SDKs handle these errors automatically and provide structured error objects.
Validation Errors
json
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "The attachments field validation failed",
"details": {
"attachments.0.name": ["The attachment name is required"],
"attachments.0.data": ["The attachment data must be a string"]
}
}
}1
2
3
4
5
6
7
8
9
10
11
2
3
4
5
6
7
8
9
10
11
File Size Exceeded
json
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "The total size of the attachments must be smaller than 10MB"
}
}1
2
3
4
5
6
7
2
3
4
5
6
7
Too Many Attachments
json
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "The attachments may not have more than 10 items."
}
}1
2
3
4
5
6
7
2
3
4
5
6
7
Unsupported File Type
json
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "File type not allowed. Supported extensions: pdf, jpg, jpeg, png, docx, txt"
}
}1
2
3
4
5
6
7
2
3
4
5
6
7
🔐 SDK Security Features
Automatic Encryption
- Files encrypted using same key material as secret content
- Individual file encryption with integrity verification
- Automatic base64 encoding for secure transmission
- File type validation before encryption
File Access
- Attachments accessed through same secret URL as content
- Client-side decryption when viewing/downloading
- Automatic cleanup when secret expires
- Zero Knowledge architecture maintained
💡 SDK Implementation Notes
File Handling
All SDKs automatically handle:
- File reading and validation
- Client-side encryption before upload
- Progress tracking for large files
- Error handling and retry logic
Best Practices
- Keep total attachment size under 10MB
- Use appropriate file extensions
- Validate files client-side before encryption
- Handle upload progress for better UX
🔗 Related Documentation
- Secrets API - Main secret creation and management
- CLI C# Documentation - Command-line file handling
- JavaScript SDK - Browser and Node.js file APIs
- Python SDK - Async file processing
- Authentication - API token management