Buckets

Creating a bucket

Console
API
CLI
Go

Go to Storage → Buckets and choose Create Bucket. Bucket Name is the only thing you have to fill in; Versioning, Default encryption, Deletion protection and Tags are on the same form.Those extras are applied as separate calls once the bucket exists, so the bucket is created even if one of them fails, and the console tells you which one did.

POST https://storage.sa-saopaulo-1.basaltic.sh/v1/buckets
{ "name": "my-app-assets" }

basaltic storage bucket create --name my-app-assets

Add --object-lock-enabled here if you need it — it can only ride on the call that creates the bucket.

b, err := storage.New(cfg).CreateBucket(ctx, &storage.CreateBucketRequest{
    Name: "my-app-assets",
})

Bucket names follow the S3 rules, and they are checked in full:

3–63 characters

required

Lowercase letters, digits and hyphens. Must start and end with a letter or digit, must not contain a double hyphen (--), and must not be shaped like an IP address.

A bucket name is unique across the whole region, not just your account. A name another account already holds comes back 409. Creating a bucket you already own is a no-op that succeeds, so a repeated create is safe.

Bucket count is capped by your organization’s buckets quota; exhausting it is also a 409 on create.

Object Lock has to be decided here

POST /v1/buckets
{ "name": "audit-archive", "object_lock_enabled": true }

Object Lock can only be enabled at creation. There is no call that turns it on later — you would have to create a new bucket and copy the objects across. Enabling it also turns versioning on, because a lock has nothing to hold onto without versions.

PUT /v1/buckets/{bucket}/object-lock updates the default retention rule on a bucket that already has Object Lock enabled. Against a bucket that does not, it is a 409 — object lock must be enabled at bucket creation.

Turning Object Lock on is API only. It has to ride on the call that creates the bucket, and the console’s Create Bucket form does not send it — the bucket is created without Object Lock, and the follow-up configuration is refused with that same 409. Create the bucket through the API when you need Object Lock.On a bucket that already has it, the console does edit the rule: the Object Lock card on the bucket’s Settings tab carries the Default retention rule, with a Mode and a Retention period.

Bucket settings in the native API

The settings endpoints use the same top-level fields for GET responses and PUT requests:

Endpoint under `/v1/buckets/{bucket}`	Fields
`/cors`	`cors_rules`
`/lifecycle`	`lifecycle_rules`; reads also return `revision`
`/encryption`	`encryption_rules`
`/object-lock`	`object_lock_enabled`, `object_lock_rule`

The rules arrays have no extra configuration wrapper. Object Lock’s object_lock_rule contains default_retention. Lifecycle updates require the current revision in If-Match; see Lifecycle rules. These shapes apply to the native API. S3 clients continue to use the standard S3 configuration formats.

Pointing an S3 client at it

Set a custom endpoint and sign with your Basaltic access key. Nothing else about the client changes.

import boto3
from botocore.config import Config

s3 = boto3.client(
    "s3",
    endpoint_url="https://objects.sa-saopaulo-1.basaltic.cloud",
    aws_access_key_id=ACCESS_KEY_ID,
    aws_secret_access_key=SECRET_ACCESS_KEY,
    region_name="sa-saopaulo-1",
    config=Config(signature_version="s3v4"),
)

s3.put_object(Bucket="my-app-assets", Key="images/logo.png", Body=data)

aws --endpoint-url https://objects.sa-saopaulo-1.basaltic.cloud \
    s3 cp ./logo.png s3://my-app-assets/images/logo.png

s3 = boto3.client(
    "s3",
    endpoint_url="https://objects.sa-saopaulo-1.basaltic.cloud",
    aws_access_key_id=creds.access_key_id,
    aws_secret_access_key=creds.secret_access_key,
    aws_session_token=creds.session_token,   # required for STS credentials
    region_name="sa-saopaulo-1",
    config=Config(signature_version="s3v4"),
)

Credentials

The same access keys you use everywhere else. A service account’s long-lived key needs nothing extra; temporary credentials from STS — a role session or a user session — must also carry the session token, and are rejected without it.See authentication for how to obtain each.

Addressing style

Both styles work. Virtual-hosted (https://my-app-assets.objects.sa-saopaulo-1.basaltic.cloud/key) is what most SDKs default to; path-style (https://objects.sa-saopaulo-1.basaltic.cloud/my-app-assets/key) is available through your client’s addressing-style option.

The region string

Set region_name to the Basaltic region code. The value is not checked against the region serving the request — it only has to match what your client signed with — so a tool hard-wired to us-east-1 still works. GetBucketLocation reports the real region.

Clock skew and presigned URLs

A signed request must be within 15 minutes of the server’s clock, or it is rejected as too skewed. Presigned URLs are supported with an expiry between 1 second and 7 days, and a URL dated in the future beyond the skew tolerance is refused rather than becoming valid later.

What the S3 endpoint serves

The endpoint is verified against a real AWS SDK rather than a specification of our own — if boto3 can do it and gets S3’s error codes back, it works. What is routed today:

ListBuckets, CreateBucket, HeadBucket, DeleteBucket, GetBucketLocation, and the ?policy, ?cors, ?lifecycle, ?versioning, ?encryption, ?tagging, ?object-lock and ?acl sub-resources.

Objects

PutObject, GetObject (including range requests), HeadObject, DeleteObject, DeleteObjects, CopyObject, ListObjects, ListObjectsV2, ListObjectVersions, and the ?tagging, ?retention, ?legal-hold and ?acl sub-resources.

Multipart

CreateMultipartUpload, UploadPart, UploadPartCopy, ListParts, ListMultipartUploads, CompleteMultipartUpload, AbortMultipartUpload.

Payload signing

Signed payloads, UNSIGNED-PAYLOAD, and signed aws-chunked streaming uploads. The body is re-hashed as it streams, so a body that does not match what was signed is rejected mid-flight.

Anything outside that list answers NotImplemented. Preflight OPTIONS requests are answered without a signature, because browsers never sign them.

Deleting a bucket

DELETE /v1/buckets/{bucket} does two quite different things depending on whether deletion protection is on. Protection is deliberately off by default for S3 parity: unlike Secrets and KMS, unprotected buckets have no recovery window.

Protection off (default)
Protection on

The bucket must be empty. Any remaining objects, versions or in-flight multipart uploads make it a 409 BucketNotEmpty. An empty bucket is deleted immediately and the quota slot is released.

The delete is scheduled for the end of the recovery window rather than performed, and it is accepted whether or not the bucket is empty. deleted_at records when you requested deletion and scheduled_purge_at records the purge deadline. Buckets already in a recovery window when these fields were introduced retain their deadline and have a null deleted_at. Both timestamps are cleared on restore. POST /v1/buckets/{bucket}/restore cancels it any time before that deadline — in the console, the scheduled bucket carries a Cancel deletion action that does the same thing. Calling delete again while a deletion is already scheduled is a no-op, not a second window.

When the deadline passes, the bucket is emptied and purged — its objects go with it. Protection buys you a window to change your mind, not a refusal to delete a bucket with data in it.

Console
API
CLI
Go

The Deletion protection card on the bucket’s Settings tab is a switch alongside Recovery window (days). Save applies both.

PUT /v1/buckets/{bucket}/deletion-protection
{ "enabled": true, "recovery_window_days": 14 }

basaltic storage bucket set-deletion-protection <bucket> \
  --enabled --recovery-window-days 14

err := storage.New(cfg).PutBucketDeletionProtection(ctx, bucket,
    &storage.PutBucketDeletionProtectionRequest{
        Enabled:      true,
        RecoveryWindowDays: basaltic.Int(14),
    })

recovery_window_days accepts whole numbers from 1–30. Omitting every window field uses 7 days. Invalid values return 400, including when turning protection off.

Release note: recovery fields

Bucket responses expose recovery_window_days, scheduled_purge_at and nullable deleted_at. Protected DELETE returns 200 with scheduled_purge_at; immediate DELETE returns 204.

Breaking behavior change: invalid windows return 400

The service previously silently clamped windows: values below 1 selected 7 days, and values above 30 selected 30 days. It now rejects them with 400 instead. For example, asking for 60 days fails; it no longer schedules a purge after only 30 days. Explicit zero is also invalid; omit the window fields to select the 7-day default. Fractional days are invalid. Update callers that relied on clamping separately from adopting the new field names. During a rolling deployment, old service instances can still apply their old clamping behavior; rejection is universal once all instances are updated.

Get started

Products

Platform

Help

Buckets

Creating a bucket

Object Lock has to be decided here

Bucket settings in the native API

Pointing an S3 client at it

What the S3 endpoint serves

Buckets

Objects

Multipart

Payload signing

Deleting a bucket

Release note: recovery fields

Breaking behavior change: invalid windows return 400

​Creating a bucket

​Object Lock has to be decided here

​Bucket settings in the native API

​Pointing an S3 client at it

​What the S3 endpoint serves

Buckets

Objects

Multipart

Payload signing

​Deleting a bucket

​Release note: recovery fields

​Breaking behavior change: invalid windows return 400

Creating a bucket

Object Lock has to be decided here

Bucket settings in the native API

Pointing an S3 client at it

What the S3 endpoint serves

Deleting a bucket

Release note: recovery fields

Breaking behavior change: invalid windows return 400