Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/deuxfleurs-org/garage/llms.txt

Use this file to discover all available pages before exploring further.

Garage implements AWS Signature Version 4 authentication for S3 API requests. This page describes how authentication works and how to configure your S3 clients.

​
Authentication Methods

Garage supports the following authentication methods:

Signature v4

Standard AWS authentication using signature version 4

Presigned URLs

Time-limited URLs with embedded authentication
Signature v2 (deprecated by AWS) is not supported by Garage.

​
AWS Signature Version 4

Garage uses the same authentication mechanism as Amazon S3, based on HMAC-SHA256 signatures.

​
Request Signing Process

When making authenticated requests to Garage:
  1. Create a canonical request - Normalize the HTTP request into a standard format
  2. Create a string to sign - Combine request metadata with the canonical request hash
  3. Calculate the signature - Use your secret key to generate an HMAC-SHA256 signature
  4. Add signature to request - Include the signature in the Authorization header

​
Authorization Header Format

The Authorization header follows this format: 
Authorization: AWS4-HMAC-SHA256 Credential={access_key}/{date}/{region}/s3/aws4_request,
  SignedHeaders={signed_headers},
  Signature={signature}
​
access_key
string
required
Your Garage access key ID
​
date
string
required
Date in YYYYMMDD format (e.g., “20260304”)
​
region
string
required
The S3 region configured in your Garage instance (default: “garage”)
​
signed_headers
string
required
Semicolon-separated list of headers included in the signature
​
signature
string
required
The calculated HMAC-SHA256 signature as hexadecimal string

​
Presigned URLs

Garage supports presigned URLs that allow temporary access to objects without requiring credentials.

​
Creating Presigned URLs

Presigned URLs embed authentication information in query parameters: 
curl "https://s3.garage.example.com/my-bucket/file.txt?
  X-Amz-Algorithm=AWS4-HMAC-SHA256&
  X-Amz-Credential={access_key}/20260304/garage/s3/aws4_request&
  X-Amz-Date=20260304T120000Z&
  X-Amz-Expires=3600&
  X-Amz-SignedHeaders=host&
  X-Amz-Signature={signature}"
​
X-Amz-Algorithm
string
required
Signature algorithm, must be AWS4-HMAC-SHA256
​
X-Amz-Credential
string
required
Access key and scope in format: {access_key}/{date}/{region}/s3/aws4_request
​
X-Amz-Date
string
required
ISO 8601 timestamp when the signature was created
​
X-Amz-Expires
integer
required
Number of seconds until the URL expires (max: 604800 / 7 days)
​
X-Amz-SignedHeaders
string
required
List of headers that were signed
​
X-Amz-Signature
string
required
The presigned URL signature

​
Example: Generate Presigned URL with AWS CLI

aws s3 presign s3://my-bucket/file.txt \
  --endpoint-url https://s3.garage.example.com \
  --expires-in 3600

​
URL Styles

Garage supports both path-style and virtual-hosted-style URLs: 
https://s3.garage.example.com/bucket-name/object-key
Virtual-hosted-style URLs require proper DNS configuration with wildcard support.

​
Authentication Errors

Common authentication error responses:
Error CodeHTTP StatusDescription
AccessDenied403Invalid credentials or insufficient permissions
SignatureDoesNotMatch403Signature calculation error
InvalidAccessKeyId403Access key does not exist
RequestTimeTooSkewed403Request timestamp is too far from server time
ExpiredToken400Presigned URL has expired

​
Client Configuration

​
AWS CLI

aws configure set aws_access_key_id GK...
aws configure set aws_secret_access_key ...
aws configure set region garage
aws configure set s3.endpoint_url https://s3.garage.example.com

​
boto3 (Python)

import boto3

s3 = boto3.client('s3',
    endpoint_url='https://s3.garage.example.com',
    aws_access_key_id='GK...',
    aws_secret_access_key='...',
    region_name='garage'
)

​
AWS SDK for JavaScript

const { S3Client } = require('@aws-sdk/client-s3');

const s3 = new S3Client({
  endpoint: 'https://s3.garage.example.com',
  region: 'garage',
  credentials: {
    accessKeyId: 'GK...',
    secretAccessKey: '...'
  }
});

​
Server-Side Encryption (SSE-C)

Garage supports customer-provided encryption keys (SSE-C): 
curl -X PUT https://s3.garage.example.com/bucket/object \
  -H "x-amz-server-side-encryption-customer-algorithm: AES256" \
  -H "x-amz-server-side-encryption-customer-key: {base64-key}" \
  -H "x-amz-server-side-encryption-customer-key-MD5: {base64-md5}" \
  --data-binary @file.txt
​
x-amz-server-side-encryption-customer-algorithm
string
Encryption algorithm, must be AES256
​
x-amz-server-side-encryption-customer-key
string
Base64-encoded 256-bit encryption key
​
x-amz-server-side-encryption-customer-key-MD5
string
Base64-encoded MD5 digest of the encryption key
SSE-C requires HTTPS. The encryption key must be provided with every request to access encrypted objects.

​
See Also