S3-Kompatibilität

Blob Storage spricht die S3-API unter https://s3-blob.squarecloud.app. Jedes Tool, bei dem du einen eigenen Endpoint festlegen kannst, funktioniert: aws-cli, boto3, das AWS SDK für JavaScript, rclone, Cyberduck und die meisten Backup-Tools.

Zugangsdaten

S3-Tools signieren Requests mit einem Zugangsschlüsselpaar. Hol es dir über S3 Credentials:

curl https://blob.squarecloud.app/v1/s3/credentials \
  --header 'Authorization: YOUR_API_KEY'

Das Paar wird aus deinem API-Schlüssel abgeleitet. Es braucht keine separate Verwaltung: Das Widerrufen oder Neugenerieren des Schlüssels wirkt sich genauso auf das Paar aus, und das Paar erhält dieselben Scopes. Ein Schlüssel mit nur blob:read ergibt ein reines Lese-Paar. Das Paar ändert sich nicht, solange sich der API-Schlüssel nicht ändert. Hol es also einmal ab und bewahre es in deinem Secret Manager oder in einer Umgebungsvariable auf. Ruf die Route nicht bei jedem Start auf: Sie akzeptiert 10 Requests pro Stunde.

Einstellung	Wert
Endpoint	`https://s3-blob.squarecloud.app`
Region	`auto`
Adressierung	Path-Style (`https://s3-blob.squarecloud.app/<bucket>/<key>`)
Signatur	AWS Signature Version 4

Buckets

Dein Konto sieht drei feste Buckets. Du kannst keine Buckets erstellen oder löschen.

Bucket	Inhalt	Zugriff
`public`	Öffentliche Dateien, ausgeliefert unter `https://blob.squarecloud.dev/pub/<user_id>/<key>`	Lesen und Schreiben
`private`	Private Dateien, ohne öffentliche URL	Lesen und Schreiben
`legacy`	Legacy-Dateien, hochgeladen vor dem Update im September 2026	Lesen, Auflisten und Löschen

Ein Key im Bucket public oder private ist der Objektpfad ohne deine Nutzer-ID: images/logo.png im Bucket public ist in der REST-API das Objekt pub/<user_id>/images/logo.png. Dateien, die über S3 geschrieben werden, erscheinen in der REST-API und im Dashboard, und umgekehrt.

Konfiguration

aws configure set aws_access_key_id SQ2_...
aws configure set aws_secret_access_key ...
aws configure set region auto

aws s3 cp ./logo.png s3://public/images/logo.png \
  --endpoint-url https://s3-blob.squarecloud.app
aws s3 ls s3://public/images/ --endpoint-url https://s3-blob.squarecloud.app

import boto3
from botocore.config import Config

s3 = boto3.client(
    "s3",
    endpoint_url="https://s3-blob.squarecloud.app",
    aws_access_key_id="SQ2_...",
    aws_secret_access_key="...",
    region_name="auto",
    config=Config(signature_version="s3v4", s3={"addressing_style": "path"}),
)

s3.upload_file("report.pdf", "private", "reports/2026/report.pdf")
url = s3.generate_presigned_url(
    "get_object",
    Params={"Bucket": "private", "Key": "reports/2026/report.pdf"},
    ExpiresIn=3600,
)

import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";

const s3 = new S3Client({
  endpoint: "https://s3-blob.squarecloud.app",
  region: "auto",
  forcePathStyle: true,
  credentials: { accessKeyId: "SQ2_...", secretAccessKey: "..." },
});

await s3.send(new PutObjectCommand({
  Bucket: "public",
  Key: "images/logo.png",
  Body: buffer,
  ContentType: "image/png",
}));

[squarecloud]
type = s3
provider = Other
access_key_id = SQ2_...
secret_access_key = ...
endpoint = https://s3-blob.squarecloud.app
region = auto
force_path_style = true

boto3 braucht signature_version="s3v4" für Presigned URLs: Ohne diese Einstellung signiert generate_presigned_url mit dem älteren SigV2, das das Gateway nicht akzeptiert. Presigned URLs gelten bis zu 7 Tage (604800 Sekunden).

Antworten des Gateways werden nie an der Edge gecacht. Eine Presigned URL funktioniert genau dann nicht mehr, wenn sie abläuft, wenn der API-Schlüssel widerrufen wird oder wenn das Objekt gelöscht wird.

Unterstützte Operationen

Bereich	Operationen
Buckets	`ListBuckets`, `HeadBucket`, `GetBucketLocation`. `CreateBucket` auf einen bestehenden Bucket ist erfolgreich; `DeleteBucket` antwortet mit `BucketNotEmpty`, solange der Bucket Dateien enthält.
Auflisten	`ListObjects` und `ListObjectsV2`, mit `delimiter`, `prefix` und `encoding-type=url`.
Objekte	`HeadObject`, `GetObject` (mit `Range`, `If-Match`, `If-None-Match`, `If-Modified-Since`), `PutObject` (bis 100 MB in einem Request), `CopyObject` (Metadaten-Direktiven `COPY` und `REPLACE`), `DeleteObject`, `DeleteObjects` (bis 1000 Keys).
Multipart	`CreateMultipartUpload`, `UploadPart` (5 MB bis 80 MB pro Teil, außer dem letzten), `UploadPartCopy`, `CompleteMultipartUpload`, `AbortMultipartUpload`, `ListParts`, `ListMultipartUploads`. Objekte bis 10 GiB.
Integrität	`Content-MD5` wird immer verifiziert, auch wenn zusätzlich ein `x-amz-checksum-*`-Header gesendet wird. `x-amz-checksum-crc32`, `-sha1` und `-sha256` werden ebenfalls verifiziert; eine Abweichung antwortet mit `BadDigest`. `crc32c` und `crc64nvme` werden ohne Verifizierung akzeptiert. `aws-chunked`-Bodys werden unterstützt.
Kompatibilität	`GetBucketVersioning`, `GetBucketAcl`, `GetObjectAcl` und die Tagging-Lesezugriffe antworten mit festen Werten, damit Tools, die sie abfragen, weiter funktionieren.

Bucket Policies, CORS, Lifecycle, Website, Verschlüsselung, Object Lock, Versionen, Logging, Benachrichtigungen, Replikation, ACL- und Tag-Schreibzugriffe, GET per partNumber sowie Browser-POST-Formular-Uploads antworten mit 501 NotImplemented. Verwende die Kontoeinstellungen für Lifecycle-Regeln.

Keys

Keys sind wörtliche Pfade. Ein Key kann bis zu etwa 1000 Bytes lang sein: Das Limit von 1024 Bytes zählt auch das Kontopräfix mit. Ein längerer Key antwortet mit KeyTooLongError, und die Meldung nennt die genaue Anzahl an Bytes, die dir zur Verfügung stehen. Segmente dürfen nicht leer, . oder .. sein.
Ein 0-Byte-Key, der auf / endet, ist ein Ordner-Marker, so wie die AWS-Konsole Ordner erstellt.
Der ausgelieferte Content-Type wird wie in der REST-API aus der Endung bestimmt. Ausführbare Dateien werden mit InvalidArgument abgelehnt, und .html, .svg und .xml werden als Downloads ausgeliefert.

Metadaten, Cache und Ablauf

x-amz-meta-*-Header bleiben bei Pro und Enterprise erhalten (bis zu 5 Schlüssel und 512 Bytes, sonst MetadataTooLarge). Bei anderen Plänen werden sie verworfen.
Cache-Control und Content-Disposition bleiben erhalten. Ein Cache-Control ohne Caching (no-cache, no-store oder max-age=0) wird außerhalb von Enterprise mit AccessDenied abgelehnt.
Regeln pro Präfix gelten für Objekte, die über S3 geschrieben werden, einschließlich der automatischen Löschung. max_size und extensions einer Regel gelten nur für REST-Uploads.

Limits

Limit	Wert
Requests pro Konto, alle 10 Sekunden	Hobby 100 · Standard 200 · Pro 400 · Enterprise 600
Serverseitige Kopien (`CopyObject`, `UploadPartCopy`)	20 pro 10 Sekunden
Per `DeleteObjects` gelöschte Keys	2000 pro 10 Sekunden
Offene Multipart-Uploads	32 pro Konto, geteilt mit den Chunked Uploads der REST-API
Einzelnes `PutObject`	100 MB
Teil (`UploadPart`)	5 MB bis 80 MB, außer dem letzten Teil
Objektgröße	10 GiB
Ungültige Zugangsdaten	Zu viele Fehlversuche sperren die IP für einige Minuten

Über einem Limit antwortet das Gateway mit SlowDown (HTTP 503), und die AWS SDKs warten und wiederholen von selbst. S3-Requests zählen nicht zum API-Request-Limit deines Plans. Prüfe das Schlüsselpaar, bevor du in einer Schleife wiederholst: Eine IP, die zu viele ungültige Zugangsdaten sendet, wird für einige Minuten gesperrt.

Teilgröße

Multipart-Tools teilen große Dateien selbst auf; halte jeden Teil bei 80 MB oder weniger. Die Standardwerte der AWS CLI (8 MB) und von rclone (5 MB) passen bereits.

aws configure set default.s3.multipart_chunksize 64MB

from boto3.s3.transfer import TransferConfig

config = TransferConfig(multipart_chunksize=64 * 1024 * 1024)
s3.upload_file("backup.tar.gz", "private", "backups/backup.tar.gz", Config=config)

import { Upload } from "@aws-sdk/lib-storage";

await new Upload({
  client: s3,
  params: { Bucket: "private", Key: "backups/backup.tar.gz", Body: stream },
  partSize: 64 * 1024 * 1024, // bis 80 MB
}).done();

Schreiben erfordert einen kostenpflichtigen Plan. Ohne einen solchen, und im reinen Lese-Bucket legacy, antworten Schreibzugriffe mit AccessDenied. Das Speicherkontingent gilt wie in der REST-API.

Fehler

Das Gateway antwortet mit Standard-S3-XML-Fehlern, sodass SDKs sie nativ verarbeiten:

Fehler	Wann
`AccessDenied`	Kein kostenpflichtiger Plan, reiner Lese-Schlüssel, Schreiben in `legacy` oder eine Option außerhalb deines Plans.
`NoSuchBucket`	Der Bucket ist nicht `public`, `private` oder `legacy`.
`NoSuchKey`	Das Objekt existiert nicht.
`InvalidArgument`	Ein gesperrter Dateityp (ausführbare Dateien und Installer) oder ein fehlerhafter Header.
`QuotaExceeded`	Das Konto hat seinen enthaltenen Speicher erreicht.
`EntityTooLarge` / `EntityTooSmall`	Ein `PutObject` über 100 MB, ein Teil über 80 MB oder ein Teil unter 5 MB, der nicht der letzte ist.
`InvalidPart` / `InvalidPartOrder` / `NoSuchUpload`	Multipart-Abschluss mit fehlerhaften Teilen oder ein Upload, der nicht mehr existiert.
`BadDigest`	Der Body stimmt nicht mit `Content-MD5` oder dem `x-amz-checksum-*`-Header überein.
`PreconditionFailed`	Eine `If-Match`- oder `If-None-Match`-Bedingung ist fehlgeschlagen.
`MetadataTooLarge`	Mehr als 5 Metadaten-Schlüssel oder 512 Bytes.
`KeyTooLongError`	Der Key ist zu lang (etwa 1000 Bytes). Die Meldung nennt das genaue Limit für dein Konto.
`SlowDown`	HTTP 503: Ein Rate Limit oder das Limit offener Uploads wurde erreicht. SDKs wiederholen von selbst mit Backoff.
`NotImplemented`	Die Operation wird nicht unterstützt (siehe oben).

Erste Schritte

Objekte

Chunked-Uploads

Konto

Freigabelinks

S3

Zugangsdaten

Buckets

Konfiguration

Unterstützte Operationen

Keys

Metadaten, Cache und Ablauf

Limits

Teilgröße

Fehler

​Zugangsdaten

​Buckets

​Konfiguration

​Unterstützte Operationen

​Keys

​Metadaten, Cache und Ablauf

​Limits

​Teilgröße

​Fehler

Zugangsdaten

Buckets

Konfiguration

Unterstützte Operationen

Keys

Metadaten, Cache und Ablauf

Limits

Teilgröße

Fehler