Skip to main content
Live. This area is documented as current, user-reliable behavior.

​
Goal

Build object workflows against the operations S2 implements and grant short-lived access without sharing long-lived keys.

​
Prerequisites

  • An S2 bucket
  • A bucket access key or StackShift API token

​
Workflow

1
Use the S3 endpoint for normal object reads, writes, listings, copies, tags, and multipart uploads.
2
Attach content headers and custom metadata when the application needs them returned with the object.
3
Use write preconditions and checksums when replacing important keys.
4
Generate a presigned URL for temporary browser, customer, or service access.
5
Use a temporary prefix-scoped key when a client needs several S3 operations instead of one URL.

​
Supported S3-compatible operations

  • ListBuckets, CreateBucket, HeadBucket, DeleteBucket, and GetBucketLocation.
  • ListObjectsV2 with prefix, delimiter, continuation token, and maximum-key controls. The local release candidate handles start-after, legacy ListObjects markers, URL encoding and max-keys=0; the dashboard now pages through the library.
  • PutObject, GetObject, HeadObject, DeleteObject, CopyObject, and DeleteObjects.
  • GET, PUT, and DELETE object tagging.
  • InitiateMultipartUpload, UploadPart, CompleteMultipartUpload, and AbortMultipartUpload. The local release candidate additionally implements paginated ListParts and ListMultipartUploads; verify the deployed release before depending on these operations.
  • GET, PUT, and DELETE bucket CORS configuration plus browser preflight handling.

​
Bulk deletion and partial recovery (release candidate)

DELETE /api/v1/buckets/{bucketID}/objects accepts keys and an optional report:true flag. Report mode returns deleted plus results containing key, deleted and, on failure, code and message. Duplicate keys are processed once. The legacy response and error behavior remain available when report is omitted. The dashboard keeps failed objects selected, explains retention or legal-hold failures and retries only remaining keys. Page and folder changes clear the selection. A deletion that cannot be confirmed requires refreshing before retry; object versions remain subject to versioning and retention policy.

​
Object headers and safe updates

  • S2 records content type, cache control, content disposition, content encoding, expiry, custom metadata, ETag, and SHA-256 checksum metadata.
  • Byte-range GET requests return partial object content for resumable downloads and media readers.
  • Conditional writes can reject an overwrite when the current ETag does not match the application expectation.
  • Release-candidate CopyObject supports an explicit source version, source ETag/date conditions, copied or replaced metadata and tags, and customer-key encryption on the source and destination. A failed source condition returns PreconditionFailed without publishing the destination. PUT accepts URL-encoded object tags.
  • Anonymous GET and HEAD are available for public current objects. Signed requests still validate their credentials; revoked or expired signatures never fall back to anonymous access. Historical version reads require authorized credentials even for public buckets.
  • PUT and UploadPart validate declared Content-MD5, SHA-256, SHA-1, CRC32 and CRC32C payload checksums before publication, including checksum values carried in signed query parameters. Conflicting declarations and unsupported checksum algorithms are rejected. A supplied payload SHA-256 is also validated.
  • In the release candidate, object keys and credential prefixes are literal UTF-8 values. Spaces, repeated slashes, backslashes and dot segments are not rewritten after authorization. Existing stored keys keep their identities; callers must request the exact stored key rather than relying on path-cleaning aliases.

​
Resumable uploads and uncertain completion (release candidate)

The local release candidate requires migration 525 for atomic multipart completion receipts. Repeating the same completion manifest returns its original object result without publishing another object or event. A different manifest for an already completed upload is rejected. Completed receipts are retained for OBJECT_STORE_MULTIPART_EXPIRY after completion (24 hours by default). Retry uncertain completion promptly; after cleanup, reconcile the destination using its expected size and checksum before starting another upload. ListParts returns each stored part SHA-256 for reselection verification. UploadPart validates an explicit SHA-256 checksum, and final assembly checks each stored part while streaming. Multipart ETags are not universal content checksums. Streaming PUT and UploadPart validate the decoded length, every signed chunk including the final empty chunk, and any declared trailer. Supported trailer checksums are SHA-256, SHA-1, CRC32 and CRC32C. Unsupported streaming modes or checksum algorithms return NotImplemented; altered signatures, checksum mismatches and malformed framing reject the write before publication. The JavaScript release candidate exports S2Uploader, createS2ResumeStore and the server-side S2UploadsClient. POST /api/v1/buckets/{bucketID}/uploads creates an upload from key, size and mimeType. POST /api/v1/buckets/{bucketID}/uploads/actions accepts action (resume, sign-part, complete or cancel), token, and part when signing. Every action rechecks authenticated bucket ownership and the encrypted context expiry. Permanent credentials stay on the server. Application uploads use 8 MiB parts and return SHA-256 evidence for completed parts. Part URLs expire after at most 15 minutes; the upload context lasts at most the configured multipart expiry or 24 hours. Completion verifies part count and sizes, and repeated completion recovers the original durable receipt. Cancelling an already completed upload does not delete its object. The executable React/Next.js example is packages/sdk-js/examples/s2-nextjs. It uses the local SDK release candidate, an authenticated same-origin server adapter, explicit bucket CORS, progress, pause, cancellation and account-scoped reload state. Replace its single-account loopback demo authentication with your application session before production use. After a browser reload, reselect the original file. Changed file metadata requires explicit cancellation before starting again; retained chunks are checked against SHA-256 before reuse. An uncertain cancellation retains recovery state. Clear account-scoped local state on logout. A saved uncertain completion is retried before attempting to list an upload that may already be complete. If its recovery window has expired, verify the destination before clearing saved state; the helper does not silently create another object. Multipart per-request encryption and initial tags are explicitly unsupported in this candidate. Bucket-managed encryption applies during final assembly; temporary parts use the existing backing-store protection. Set tags after completion. Single PUT and CopyObject support the documented per-object encryption modes; unknown or conflicting modes are rejected.

​
Presigned URLs

The control-plane presign operation supports GET, PUT, HEAD, and DELETE. It returns the URL, required signed headers, method, and expiry. The default lifetime is 15 minutes when no value is supplied. Presigned URLs are best for one object operation. Do not expose a bucket secret to a browser or download recipient when a URL can express the same access.
Create a presigned upload

​
Temporary credentials

Temporary S2 keys can expire from one second up to seven days, restrict access to one object-key prefix, and allow only selected operations. Supported operation names are get, head, put, delete, list, and multipart. The secret is returned once. Store it only for the lifetime of the delegated task and revoke the key early when the task completes.

​
Expected result

Applications use standard S3 request signing while temporary consumers receive only the method, prefix, and lifetime they need.

​
Common failures

  • Using a presigned PUT URL without the signed Content-Type header returned by the API.
  • Reusing a URL after its expiry or changing its method, path, query string, or signed headers.
  • Completing a multipart upload with missing, duplicated, or reordered part numbers and ETags.
  • Granting a temporary key a wider prefix or operation set than the client requires.

Create a bucket and connect an S3 client

Create an S2 bucket, capture its one-time credentials, and verify object operations with the AWS CLI.

Access keys, encryption, isolation, and quotas

Operate S2 credentials, encryption, visibility, tenant isolation, request limits, and customer-plan quotas safely.

Versioning, lifecycle, and retention

Protect object history, restore earlier versions, automate aging policies, and prevent protected objects from being deleted too early.