garage key - Garage

Description

The garage key commands manage S3-compatible access keys (also called API keys or credentials). These keys are used by S3 clients to authenticate and access buckets. Each key consists of:

Access Key ID: Public identifier (e.g., GK1234567890abcdef)
Secret Access Key: Private credential for signing requests
Name: Human-readable label
Permissions: What the key is allowed to do

Usage

garage key <SUBCOMMAND> [OPTIONS]

Subcommands

key list

List all access keys in the cluster.

garage key list

Displays a table with key IDs, creation dates, names, and expiration status.

key info

Get detailed information about a specific key.

garage key info [OPTIONS] <KEY_PATTERN>

KEY_PATTERN

string

required

Access key ID or name (or prefix) to look up.

--show-secret

flag

Display the secret access key in the output.By default, the secret is hidden (redacted) for security.

key create

Create a new access key.

garage key create [OPTIONS] [NAME]

NAME

string

default:"Unnamed key"

Human-readable name for the key.

--expires-in

string

Set an expiration time for the key.Format: duration string (e.g., 1y, 30d, 12h)See parse_duration for format details.

key rename

Change the name of an existing key.

garage key rename <KEY_PATTERN> <NEW_NAME>

KEY_PATTERN

string

required

Access key ID or name (or prefix) to rename.

NEW_NAME

string

required

New name for the key.

key set

Modify parameters of an existing key.

garage key set [OPTIONS] <KEY_PATTERN>

KEY_PATTERN

string

required

Access key ID or name (or prefix) to modify.

--expires-in

string

Set a new expiration time.Format: duration string (e.g., 1y, 30d, 12h)

--never-expires

flag

Remove expiration, making the key valid indefinitely.

key delete

Delete an access key.

garage key delete [OPTIONS] <KEY_PATTERN>

KEY_PATTERN

string

required

Access key ID or name (or prefix) to delete.

--yes

flag

required

Confirm deletion. Required to prevent accidental deletions.

key allow

Grant permissions to an access key.

garage key allow [OPTIONS] <KEY_PATTERN>

KEY_PATTERN

string

required

Access key ID or name (or prefix) to grant permissions to.

--create-bucket

flag

Allow the key to create buckets using S3’s CreateBucket API.By default, keys cannot create buckets (only administrators can via CLI).

key deny

Revoke permissions from an access key.

garage key deny [OPTIONS] <KEY_PATTERN>

KEY_PATTERN

string

required

Access key ID or name (or prefix) to revoke permissions from.

--create-bucket

flag

Revoke bucket creation permission.

key import

Import an existing access key (for migration or recovery).

garage key import [OPTIONS] <KEY_ID> <SECRET_KEY>

KEY_ID

string

required

Access key ID to import.

SECRET_KEY

string

required

Secret access key to import.

-n, --name

string

default:"Imported key"

Name for the imported key.

--yes

flag

required

Confirm import operation.This command is for re-importing keys previously generated by Garage. To create new keys, use key create.

key delete-expired

Delete all expired access keys.

garage key delete-expired [OPTIONS]

--yes

flag

required

Confirm deletion of all expired keys.

Examples

List All Keys

garage key list

Output:

ID                  Created     Name            Expiration
GK1a2b3c4d5e6f      2024-01-15  alice-key       never
GK9876543210ab      2024-01-20  bob-key         2025-01-20 10:30:00
GKfedcba987654      2024-02-01  temp-key        expired

Create a Key

garage key create alice-main-key

Output:

==== ACCESS KEY INFORMATION ====
Key ID:         GK1a2b3c4d5e6f7890ab
Key name:       alice-main-key
Secret key:     a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6
Created:        2024-03-04 10:30:45 +00:00
Validity:       valid
Expiration:     never

Can create buckets: false

==== BUCKETS FOR THIS KEY ====
Permissions  ID  Global aliases  Local aliases
(no buckets)

Create Key with Expiration

# Expires in 1 year
garage key create --expires-in 1y production-key

# Expires in 30 days
garage key create --expires-in 30d temporary-access

# Expires in 12 hours
garage key create --expires-in 12h debug-key

View Key Information

# View key info (secret redacted)
garage key info alice-main-key

# View with secret key visible
garage key info --show-secret alice-main-key

Output:

==== ACCESS KEY INFORMATION ====
Key ID:         GK1a2b3c4d5e6f7890ab
Key name:       alice-main-key
Secret key:     a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6
Created:        2024-03-04 10:30:45 +00:00
Validity:       valid
Expiration:     never

Can create buckets: true

==== BUCKETS FOR THIS KEY ====
Permissions  ID              Global aliases  Local aliases
RW           1a2b3c4d5e6f    my-bucket       personal
R            fedcba987654    shared-data     

Rename a Key

garage key rename alice-main-key alice-production

Grant Permissions

# Allow key to create buckets
garage key allow --create-bucket alice-production

Now Alice can create buckets via S3 API:

aws s3 mb s3://alice-new-bucket

Revoke Permissions

# Remove bucket creation permission
garage key deny --create-bucket alice-production

Set Expiration

# Set key to expire in 90 days
garage key set --expires-in 90d temp-key

# Remove expiration (make key permanent)
garage key set --never-expires temp-key

Delete a Key

# Attempt delete (shows confirmation prompt)
garage key delete old-key

# Confirm deletion
garage key delete --yes old-key

Output:

Access key GKfedcba987654 has been deleted.

Import Existing Key

# Import key from another Garage cluster
garage key import --yes \
  GK1234567890abcdef \
  a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6 \
  -n migrated-key

Delete Expired Keys

# Preview which keys would be deleted
garage key list | grep expired

# Delete all expired keys
garage key delete-expired --yes

Output:

Deleting access key `temp-key` (GKabc123...)
Deleting access key `old-test` (GKdef456...)
2 access keys have been deleted.

Complete Key Lifecycle Example

# 1. Create key for new user
garage key create alice-key
# Save the Access Key ID and Secret Key!

# 2. Create bucket
garage bucket create alice-data

# 3. Grant permissions
garage bucket allow --key alice-key --read --write alice-data

# 4. Alice can now use S3 clients
# Configure s3cmd or aws cli with the credentials

# 5. Later: rename key
garage key rename alice-key alice-production

# 6. Set expiration for security
garage key set --expires-in 1y alice-production

# 7. Rotate: create new key
garage key create alice-new-key
garage bucket allow --key alice-new-key --read --write alice-data

# 8. After Alice updates clients, delete old key
garage key delete --yes alice-production

Key Permissions

Keys have these permissions:

Global Permissions

create_bucket: Create new buckets via S3 API

Per-Bucket Permissions

(Set via garage bucket allow/deny)

read: GET, HEAD, LIST operations
write: PUT, DELETE operations
owner: Bucket configuration changes

Using Keys with S3 Clients

After creating a key, configure your S3 client:

AWS CLI

# Configure credentials
aws configure --profile garage
# AWS Access Key ID: GK1234567890abcdef
# AWS Secret Access Key: (paste secret key)
# Default region: garage
# Default output format: json

# Use with Garage endpoint
aws --profile garage --endpoint-url http://localhost:3900 s3 ls

s3cmd

# Configure s3cmd
s3cmd --configure
# Access Key: GK1234567890abcdef
# Secret Key: (paste secret key)
# S3 Endpoint: localhost:3900
# Use HTTPS: no

# Test connection
s3cmd ls

Environment Variables

export AWS_ACCESS_KEY_ID=GK1234567890abcdef
export AWS_SECRET_ACCESS_KEY=a1b2c3d4e5f6...
export AWS_ENDPOINT_URL=http://localhost:3900

aws s3 ls

Python (boto3)

import boto3

s3 = boto3.client(
    's3',
    endpoint_url='http://localhost:3900',
    aws_access_key_id='GK1234567890abcdef',
    aws_secret_access_key='a1b2c3d4e5f6...'
)

# List buckets
response = s3.list_buckets()
for bucket in response['Buckets']:
    print(bucket['Name'])

Key Expiration

Expiration is useful for:

Temporary access: Guest users, contractors
Security policy: Force key rotation
Testing: Auto-cleanup of test credentials

Expiration Examples

# Short-term access (contractor)
garage key create --expires-in 90d contractor-key

# Medium-term (annual rotation policy)
garage key create --expires-in 1y employee-key

# Test/debug (auto-cleanup)
garage key create --expires-in 24h debug-session

Monitoring Expiration

# List keys with expiration dates
garage key list

# Find keys expiring soon
garage key list | grep "2024-04"

# Clean up expired keys
garage key delete-expired --yes

Key Import Use Cases

Import keys when:

Migrating clusters: Move keys from old to new cluster
Disaster recovery: Restore from backups
Multi-cluster sync: Keep same keys across environments

Warning: Never use key import to create new keys. Always use key create for new keys. Import is only for re-importing keys that Garage previously generated.

Best Practices

Use Descriptive Names

# GOOD: Clear, descriptive names
garage key create alice-production
garage key create backup-service
garage key create cdn-sync

# BAD: Generic, unclear names
garage key create key1
garage key create test
garage key create tmp

Implement Key Rotation

# Rotate keys annually
garage key create alice-2025 --expires-in 1y
garage bucket allow --key alice-2025 --read --write my-bucket

# After updating client configs
garage key delete --yes alice-2024

Use Expiration for Security

# Force rotation with expiration
garage key create --expires-in 1y production-key

# Temporary access automatically revoked
garage key create --expires-in 7d guest-access

Limit Permissions

# Don't give create-bucket unless needed
# Most application keys don't need it
garage key create app-key
# create-bucket is false by default

# Only admin/management keys should have it
garage key create admin-key
garage key allow --create-bucket admin-key

Secure Secret Keys

Never commit secret keys to version control
Store securely in password managers or secrets management
Rotate regularly to limit exposure
Use expiration to enforce rotation
Monitor usage via logs and metrics

Troubleshooting

Key Not Found

Error: “Key not found” Solution:

# List all keys
garage key list

# Search by prefix
garage key info GK123

Authentication Failed

Error: “SignatureDoesNotMatch” or “InvalidAccessKeyId” Solution:

# Verify key exists and is not expired
garage key info my-key

# Check secret key (be careful with sensitive data)
garage key info --show-secret my-key

# Verify key has bucket permissions
garage bucket info my-bucket

Key Expired

Error: Key shows as “expired” in listing Solution:

# Remove expiration
garage key set --never-expires my-key

# Or create new key
garage key create new-key
garage bucket allow --key new-key --read --write my-bucket

Can’t Delete Key

Must use --yes flag:

garage key delete --yes old-key

Commands

Configuration

Documentation Index

​Description

​Usage

​Subcommands

​key list

​key info

​key create

​key rename

​key set

​key delete

​key allow

​key deny

​key import

​key delete-expired

​Examples

​List All Keys

​Create a Key

​Create Key with Expiration

​View Key Information

​Rename a Key

​Grant Permissions

​Revoke Permissions

​Set Expiration

​Delete a Key

​Import Existing Key

​Delete Expired Keys

​Complete Key Lifecycle Example

​Key Permissions

​Global Permissions

​Per-Bucket Permissions

​Using Keys with S3 Clients

​AWS CLI

​s3cmd

​Environment Variables

​Python (boto3)

​Key Expiration

​Expiration Examples

​Monitoring Expiration

​Key Import Use Cases

​Best Practices

​Use Descriptive Names

​Implement Key Rotation

​Use Expiration for Security

​Limit Permissions

​Secure Secret Keys

​Troubleshooting

​Key Not Found

​Authentication Failed

​Key Expired

​Can’t Delete Key

Build docs developers (and LLMs) love

Description

Usage

Subcommands

key list

key info

key create

key rename

key set

key delete

key allow

key deny

key import

key delete-expired

Examples

List All Keys

Create a Key

Create Key with Expiration

View Key Information

Rename a Key

Grant Permissions

Revoke Permissions

Set Expiration

Delete a Key

Import Existing Key

Delete Expired Keys

Complete Key Lifecycle Example

Key Permissions

Global Permissions

Per-Bucket Permissions

Using Keys with S3 Clients

AWS CLI

s3cmd

Environment Variables

Python (boto3)

Key Expiration

Expiration Examples

Monitoring Expiration

Key Import Use Cases

Best Practices

Use Descriptive Names

Implement Key Rotation

Use Expiration for Security

Limit Permissions

Secure Secret Keys

Troubleshooting

Key Not Found

Authentication Failed

Key Expired

Can’t Delete Key