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

# 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.

<Tip>
  **Live.** This area is documented as current, user-reliable behavior.
</Tip>

## Goal

Complete a safe first upload and download through the production S2 endpoint.

## Prerequisites

* A StackShift API token
* AWS CLI v2 or another Signature V4-compatible client

## Workflow

<Steps>
  <Step>
    Create a private bucket with a unique lowercase name.
  </Step>

  <Step>
    Store the returned secret access key immediately; it is not returned by later reads.
  </Step>

  <Step>
    Export the returned endpoint, region, access key ID, and secret only in the current shell or a secret manager.
  </Step>

  <Step>
    Upload, list, download, and delete a test object.
  </Step>

  <Step>
    Remove the temporary local file and shell credentials when verification is complete.
  </Step>
</Steps>

## Create through the control plane

The management API uses your StackShift bearer token. The returned S3 credentials are scoped to the created bucket and are separate from the bearer token.

```bash Create a private bucket theme={null}
curl --fail-with-body -X POST \
  https://api.stackshift.cloud/api/v1/buckets/ \
  -H "Authorization: Bearer $STACKSHIFT_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"name":"example-customer-uploads","region":"global","visibility":"private","label":"production-app"}'
```

## Verify with the AWS CLI

Substitute values from the create response. Environment variables keep the example profile-free, but a production workload should load them from its secret manager.

```bash Upload and read an object theme={null}
export AWS_ACCESS_KEY_ID="<returned-access-key-id>"
export AWS_SECRET_ACCESS_KEY="<returned-secret-access-key>"
export AWS_DEFAULT_REGION="<returned-region>"
export S2_ENDPOINT="https://storage.stackshift.cloud"

printf "S2 is ready\n" > s2-check.txt
aws --endpoint-url "$S2_ENDPOINT" s3api put-object --bucket example-customer-uploads --key checks/ready.txt --body s2-check.txt
aws --endpoint-url "$S2_ENDPOINT" s3api list-objects-v2 --bucket example-customer-uploads --prefix checks/ --delimiter /
aws --endpoint-url "$S2_ENDPOINT" s3api get-object --bucket example-customer-uploads --key checks/ready.txt restored.txt
cmp s2-check.txt restored.txt
aws --endpoint-url "$S2_ENDPOINT" s3api delete-object --bucket example-customer-uploads --key checks/ready.txt
```

## Use prefixes as directories

* Use predictable keys such as `tenant-id/resource-id/filename` when one application serves many customers.
* List with `prefix=customers/42/` to stay inside one logical directory.
* Use `delimiter=/` to ask S2 for immediate child prefixes instead of every nested object.
* Do not rely on empty folders. A folder appears when at least one key uses its prefix unless you deliberately create a zero-byte marker object.

## Expected result

<Check>
  The client can write and read an object through `https://storage.stackshift.cloud` using only the new bucket-scoped key.
</Check>

## Common failures

<Warning>
  * Dropping the secret from the create response. Create another bucket key and revoke the lost one; secrets cannot be read back.
  * Signing with a hard-coded AWS region instead of the region returned with the S2 credentials.
  * Using virtual-host-only client settings. Configure path-style access when the client does not infer it for a custom endpoint.
  * Calling an operation outside the documented S2 compatibility surface. S2 supports PUT, GET, HEAD, DELETE, ListObjectsV2, byte-range downloads, and multipart uploads; manage buckets and access keys through the StackShift API.
</Warning>

## Related guides

<CardGroup cols={2}>
  <Card title="S2 object storage overview" href="/object-storage/overview">
    Understand the S3-compatible S2 surface, its bucket model, security boundaries, data controls, and application workflows.
  </Card>

  <Card title="Access keys, encryption, isolation, and quotas" href="/object-storage/access-and-security">
    Operate S2 credentials, encryption, visibility, tenant isolation, request limits, and customer-plan quotas safely.
  </Card>

  <Card title="Manage S2 buckets with Terraform" href="/object-storage/terraform">
    Declare an S2 bucket, handle its one-time credentials, import existing buckets, and control destructive cleanup.
  </Card>
</CardGroup>