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

# Access keys, encryption, isolation, and quotas

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

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

## Goal

Give each workload the minimum S2 access it needs and understand how the platform enforces boundaries.

## Prerequisites

* An existing S2 bucket
* Permission to manage the bucket through the StackShift API

## Workflow

<Steps>
  <Step>
    Keep buckets private unless every object in the bucket is intended for unauthenticated reads.
  </Step>

  <Step>
    Issue a separate labeled access key for each workload or deployment environment.
  </Step>

  <Step>
    Store the one-time secret in the workload secret manager.
  </Step>

  <Step>
    Rotate by creating a replacement key, deploying it, verifying use, and revoking the old key.
  </Step>

  <Step>
    Choose the bucket encryption default that matches the workload data policy.
  </Step>

  <Step>
    Track object bytes and counts against the owning customer plan.
  </Step>
</Steps>

## Two authentication planes

* Control-plane operations use a StackShift bearer token to create, inspect, delete, and manage keys for buckets owned by that tenant.
* Object operations use S3 Signature Version 4 with a bucket-scoped access key and secret.
* Storage-service and recovery credentials remain platform-internal and are never exposed as customer bucket credentials.

## Credential lifecycle

The initial key is created with the bucket. Additional keys can be labeled, listed, and revoked through the bucket management API. Only the access key ID is listable; the secret is shown once at creation.

Use overlapping rotation: create a new key, deploy it, observe successful traffic, then revoke the old key. Revocation is the recovery action for a suspected leak.

## Tenant and bucket isolation

The control plane authorizes bucket management against the authenticated owner. The S3 gateway resolves the access key to one principal and rejects operations outside that key’s bucket. Object metadata and quota accounting remain tied to the owning tenant.

## Server-side encryption

`none` stores new objects without the S2 encryption layer. `sse-s2` encrypts new objects with StackShift-managed local key material. `sse-kms` uses StackShift's platform KMS key for envelope encryption.

Customers select the mode but never provide AWS credentials or choose an arbitrary KMS key. When `sse-kms` is active, the bucket response exposes the platform key identifier for auditability. If the platform KMS integration is unavailable, the settings update and KMS-backed writes fail closed.

Changing the bucket default affects new writes. Existing objects keep the encryption mode and key metadata recorded when they were written; changing the setting does not rewrite historical objects.

```bash Enable platform-managed KMS with the CLI theme={null}
stackshift bucket settings <bucket-id> --data '{
  "versioning_enabled": true,
  "quota_bytes": null,
  "default_retention_days": 30,
  "tier_after_days": 0,
  "website_enabled": false,
  "website_index": "index.html",
  "website_error": "",
  "encryption_mode": "sse-kms",
  "custom_domain_id": null
}'
```

## Visibility, quotas, and rate limits

* Private is the default and requires a valid signature for reads and writes.
* Public visibility permits unauthenticated GET requests for object keys; mutations still require a valid bucket key.
* Customer-plan limits and optional per-bucket quotas are enforced independently.
* Requests above the gateway allowance return `429 SlowDown` with `Retry-After: 60`.
* Quota exhaustion returns an S3 `QuotaExceeded` error; delete unused objects or move to a plan with more storage.

## Expected result

<Check>
  A leaked workload key is limited to one bucket and can be rotated without changing the bucket or other workloads.
</Check>

## Common failures

<Warning>
  * Sharing one bucket key across unrelated applications or environments.
  * Logging the create-key response or committing S3 credentials to source control.
  * Marking a mixed-content bucket public. Public visibility permits unauthenticated object GETs.
  * Retrying `429 SlowDown` immediately instead of respecting `Retry-After` and adding backoff.
  * Supplying an AWS account, credential, or arbitrary KMS key ARN. `sse-kms` uses the StackShift-managed platform key.
</Warning>

## Related guides

<CardGroup cols={2}>
  <Card title="Create a bucket and connect an S3 client" href="/object-storage/create-and-connect">
    Create an S2 bucket, capture its one-time credentials, and verify object operations with the AWS CLI.
  </Card>

  <Card title="S3 operations and presigned access" href="/object-storage/s3-operations-and-presigned-access">
    Use the supported S3 operations, conditional requests, object metadata, tags, multipart uploads, and presigned URLs.
  </Card>

  <Card title="Versioning, lifecycle, and retention" href="/object-storage/versioning-lifecycle-and-retention">
    Protect object history, restore earlier versions, automate aging policies, and prevent protected objects from being deleted too early.
  </Card>

  <Card title="Security and connections" href="/settings/security-and-connections">
    Manage password changes, active sessions, GitHub app installs, and other connected-account behavior from the settings area.
  </Card>
</CardGroup>