Skip to navigation

Using the S3 API

The S3 API is a set of web requests — the one Amazon S3 uses — to upload, download and list files. IBEE Object Storage speaks the common parts of it, so most S3 tools and libraries work after you change three settings: the endpoint, the region and the addressing style. This page lists those settings, shows working examples, says which S3 calls IBEE serves and which it doesn’t, and explains the errors you may see.

When to use the S3 API

IBEE Object Storage has two APIs. They split the work the same way the portal does.

You want to…UseSign in with
Upload, download, list, copy and delete files; multipart uploads; presigned URLsS3 API (this page) at https://WORKSPACE-ID.blob.ibeestorage.comAn S3 credential
Create and delete buckets; Public Access; lifecycle, CORS, Object Lock defaults, event notifications, custom domains; bucket metrics; S3 credentialsIBEE REST API at https://api.ibee.ai/v1/object-storage/…A platform API token
Do any of the above by handThe portalYour IBEE login

How it works

  1. Your tool signs each request with your Secret Access Key, using AWS Signature Version 4 (SigV4). The signature includes the region, which must be auto.
  2. The request goes to your workspace’s endpoint, with the bucket name in the path: https://WORKSPACE-ID.blob.ibeestorage.com/my-bucket/photo.jpg.
  3. IBEE checks the signature, the clock (within 15 minutes) and the credential’s permission level, then runs the operation or returns an XML error.

Before you begin

  • An S3 credential — Access Key ID and Secret Access Key — for the bucket’s workspace, with a permission level that allows what you want to do (for example Object Read & Write to upload). See API Credentials.
  • Your S3 Endpoint, shown when you create the credential: https://WORKSPACE-ID.blob.ibeestorage.com.
  • A bucket. Create buckets in the portal, so you can choose the location. The REST API can do this too once its management resumes. See Buckets.
  • A current version of your tool. Recent AWS CLI v2 and SDK versions add an upload checksum automatically, which IBEE needs for some uploads (see Troubleshooting).

The three settings every tool needs

SettingValueIf you skip it
Endpointhttps://WORKSPACE-ID.blob.ibeestorage.comRequests go to Amazon instead of IBEE
RegionautoMost tools default to us-east-1, which fails with Invalid region scope
Addressing stylepathThe tool puts the bucket in the hostname, which doesn’t resolve

Connect your tool

1

Configure the AWS CLI

Save the credential as a profile called ibee:

aws configure set aws_access_key_id YOUR-ACCESS-KEY-ID --profile ibee
aws configure set aws_secret_access_key YOUR-SECRET-ACCESS-KEY --profile ibee
aws configure set region auto --profile ibee
aws configure set s3.addressing_style path --profile ibee
2

Run a first command

List your buckets. Pass the endpoint and profile on every command:

aws s3 ls --endpoint-url https://WORKSPACE-ID.blob.ibeestorage.com --profile ibee
2026-10-30 09:12:44 my-first-bucket
3

Upload, download and delete

# Upload one file
aws s3 cp ./report.pdf s3://my-bucket/reports/report.pdf \
--endpoint-url https://WORKSPACE-ID.blob.ibeestorage.com --profile ibee
# Upload a folder, deleting remote files that no longer exist locally
aws s3 sync ./site s3://my-bucket/site --delete \
--endpoint-url https://WORKSPACE-ID.blob.ibeestorage.com --profile ibee
# Download
aws s3 cp s3://my-bucket/reports/report.pdf ./report.pdf \
--endpoint-url https://WORKSPACE-ID.blob.ibeestorage.com --profile ibee
# Delete everything under a prefix
aws s3 rm s3://my-bucket/reports/ --recursive \
--endpoint-url https://WORKSPACE-ID.blob.ibeestorage.com --profile ibee

SDKs

Set the same three values when you create the client. These examples upload a file and list the bucket.

import boto3
from botocore.config import Config
s3 = boto3.client(
"s3",
endpoint_url="https://WORKSPACE-ID.blob.ibeestorage.com",
aws_access_key_id="YOUR-ACCESS-KEY-ID",
aws_secret_access_key="YOUR-SECRET-ACCESS-KEY",
region_name="auto",
config=Config(signature_version="s3v4", s3={"addressing_style": "path"}),
)
s3.upload_file("report.pdf", "my-bucket", "reports/report.pdf")
for obj in s3.list_objects_v2(Bucket="my-bucket", Prefix="reports/").get("Contents", []):
print(obj["Key"], obj["Size"])

With rclone, test the remote with rclone lsd ibee:, which lists your buckets.

Verify

Run aws s3 ls s3://my-bucket/ --endpoint-url https://WORKSPACE-ID.blob.ibeestorage.com --profile ibee. A list of keys (or an empty result for an empty bucket) means the endpoint, region, path style and credential are all right. Any error comes back as XML with a Code and a Message; look it up in Troubleshooting.

S3 operations IBEE serves

GroupOperations
ObjectsPutObject, GetObject (including byte ranges), HeadObject, CopyObject, DeleteObject, DeleteObjects (up to 1,000 keys per request)
ListingListObjectsV2 (up to 1,000 keys per page), ListBuckets
Multipart uploadsCreateMultipartUpload, UploadPart, UploadPartCopy, ListParts, CompleteMultipartUpload, AbortMultipartUpload, ListMultipartUploads
Bucket readsHeadBucket, GetBucketLocation, GetBucketVersioning
LinksPresigned URLs for the object operations (GET, PUT, HEAD, DELETE)

A “folder” is just a key prefix; Create Folder in the portal makes an empty object whose key ends in /.

S3 calls that return 501 Not Implemented

Other S3 calls — bucket configuration, tagging, ACLs and per-object retention among them — return 501 with the code NotImplemented and the message The requested S3 operation or query combination is not supported. Use the portal instead, or the REST API once its management resumes:

S3 callUse instead
PutBucketLifecycleConfiguration, GetBucketLifecycleConfigurationPUT / GET /v1/object-storage/buckets/{bucket_name}/lifecycle, or Settings → Lifecycle Policies
PutBucketCors, GetBucketCors, DeleteBucketCorsPUT / GET / DELETE …/cors, or Settings → CORS
PutBucketNotificationConfigurationPUT …/notifications, or Settings → Event Notifications
PutObjectLockConfigurationPUT …/object-lock (default retention only), or Settings → Lock Settings
PutBucketPolicy, PutBucketAcl, PutObjectAclPATCH /v1/object-storage/buckets/{bucket_name} with is_public, or Settings → General → Public Access
PutObjectRetention, PutObjectLegalHoldThe portal: the object’s Set Retention and Set Legal Hold actions
PutBucketVersioningTurn on Object lock (WORM) when you create the bucket
PutObjectTagging, PutBucketWebsite, PutBucketEncryptionNot available
Presigned POST (browser form uploads)Use a presigned PUT link

Limits and timing

Value
Upload in one request (PutObject)Up to 5 GiB
Multipart uploadUp to 10,000 parts, each up to 5 GiB
Key lengthUp to 1,024 bytes (UTF-8)
Keys per DeleteObjects request1,000
Keys per list page1,000
Clock tolerance15 minutes between your computer and IBEE
Presigned URL lifetime1 second to 7 days
SigningSigV4 only, region auto
Too many requests503 SlowDown. SDKs retry automatically.

Troubleshooting

You seeWhat it meansWhat to do
403 AccessDenied — Invalid region scopeThe request was signed with a region other than auto, usually us-east-1Set the region to auto in the tool or client.
”Could not resolve host” for my-bucket.WORKSPACE-ID.blob.ibeestorage.comThe tool used virtual-hosted addressingSet the addressing style to path (forcePathStyle: true, force_path_style = true).
403 SignatureDoesNotMatchThe secret key is wrong, or the request changed after it was signedCopy the Secret Access Key again; check for a proxy that rewrites headers.
403 AccessDenied — Request has expiredYour computer’s clock is more than 15 minutes off, or a presigned link expiredSync the clock; create a new link.
403 AccessDenied — Invalid access key or Access key is not activeThe credential was mistyped, revoked or deletedUse an active credential.
403 AccessDenied — Access key does not belong to this workspaceThe endpoint belongs to a different workspace from the credentialUse the endpoint shown with the credential.
403 AccessDenied (no other message)The credential’s permission level or bucket list doesn’t allow this callCreate a credential with the right level, for example Object Read & Write for uploads.
403 AccessDenied — Unsigned payload requires a signed checksumThe tool uploaded without signing the body and without a checksumUpdate the AWS CLI or SDK — current versions send a checksum — or enable Content-MD5 or checksums in the tool.
501 NotImplemented — AWS streaming payload signatures are not supportedThe SDK signs uploads chunk by chunk (STREAMING-AWS4-HMAC-SHA256-PAYLOAD)Update the SDK, or turn off chunked payload signing in its S3 settings.
501 NotImplemented — The requested S3 operation or query combination is not supportedThat S3 call isn’t servedUse the portal; see the table above.
404 NoSuchBucket or NoSuchKeyThe bucket or key name is wrong (names are case-sensitive)Check the name and the full key.
503 SlowDownYou sent requests faster than the rate limitRetry with backoff; spread requests over time.