> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onebucket.io/llms.txt
> Use this file to discover all available pages before exploring further.

# S3 API compatibility

> What the OneBucket S3 gateway supports — auth, buckets, objects, multipart, versioning, and presigned URLs.

OneBucket speaks the standard S3 API with **AWS SigV4** authentication. Any S3 client or SDK works — just point it at your endpoint:

```text theme={null}
https://s3.<cluster>.onebucket.io
```

Copy the exact host and an access key / secret key pair from your [OneBucket console](https://app.onebucket.io).

<Note>
  Because it's standard S3, the same endpoint and keys work with AWS SDKs in any language, the AWS CLI, `s3cmd`, rclone, and most S3-compatible tools. See the [Quickstart](/quickstart) for AWS CLI and boto3 examples.
</Note>

## Authentication

* **AWS Signature Version 4 (SigV4)** request signing, exactly as with AWS S3.
* Credentials are the access key / secret key pairs from your console; manage them with `onebucket keys` in the [CLI](/reference/cli).
* **Region: use `us-east-1`.** The region in your credential scope is used for signature derivation (as SigV4 requires), not for routing — the endpoint determines routing. The gateway is currently lenient about the region value, but don't rely on arbitrary names: configure `us-east-1` (empty and `auto` also resolve to it), and future releases may reject other values.

## Addressing styles

Both S3 addressing styles are supported. The gateway first looks for a bucket prefix in the hostname, then falls back to the first path segment:

| Style          | Example                                           |
| -------------- | ------------------------------------------------- |
| Virtual-hosted | `https://my-bucket.s3.<cluster>.onebucket.io/key` |
| Path-style     | `https://s3.<cluster>.onebucket.io/my-bucket/key` |

<Note>
  Virtual-hosted style requires DNS resolution of bucket subdomains. If your environment can't resolve them, configure your client for path-style addressing (e.g. `s3.addressing_style = path` in boto3).
</Note>

## Supported features

| Area              | Support                                                      |
| ----------------- | ------------------------------------------------------------ |
| Bucket operations | Create, list, and delete buckets                             |
| Object operations | PUT, GET, HEAD, DELETE, LIST (prefix, delimiter, paging)     |
| Multipart uploads | Supported for large objects                                  |
| Versioning        | Supported                                                    |
| Presigned URLs    | Time-limited GET and PUT URLs (\~1 hour validity)            |
| Copy              | Server-side copy; across backends, copies run asynchronously |

## OneBucket-specific behavior

Behind the standard API, requests resolve against the [Adaptive Data Fabric](/concepts/architecture):

* A bucket is **logical** — its objects may be held by different backends (AWS S3, Azure Blob, GCS, Wasabi, Akave, on-prem, edge, air-gapped) while clients see one namespace.
* Cross-backend `copy`, `move`, and `migrate` operations are **asynchronous**: they return once queued, and the destination may not be readable immediately.
* Repeat reads of hot objects are served from the **edge cache**; prefetching keeps first reads fast too.
* All activity is emitted as **storage events**, queryable over the events MCP endpoint.

## Errors

The gateway returns standard S3 XML error responses (e.g. `NoSuchBucket`, `NoSuchKey`, `AccessDenied`), so existing SDK error handling works unchanged.