---
title: "Rotate bucket credentials"
method: POST
path: "/v1/buckets/{bucket_id}/credentials"
tags: ["buckets"]
---

# Rotate bucket credentials

`POST /v1/buckets/{bucket_id}/credentials`

## Request

- Base URL: `https://api.mixedbread.com`
- URL: `https://api.mixedbread.com/v1/buckets/{bucket_id}/credentials`
- Auth: HTTP bearer

Replace a bucket's stored credentials.

Only available for `access_key` buckets — `assume_role` buckets store no
credentials (manage access via the role's trust policy instead). The new
credentials are re-validated against the bucket's existing (immutable) identity
before they are persisted. The credentials version is bumped so cached storage clients rebuild.

Args:
    bucket_id: The ID of the bucket to rotate credentials for.
    params: The new bucket access credentials.

Returns:
    Bucket: The updated bucket. Credentials are never returned.

## Path parameters

- `bucket_id` string, uuid, required: The ID of the bucket to rotate credentials for

## Request body

- BucketRotateCredentialsParams: Parameters for rotating a bucket's credentials.
  - `credentials` BucketAccessKeyCredentials, required: AWS-style access key credentials for a customer bucket (write-only, never returned).
    - `type` 'access_key'
    - `access_key_id` string, required: Access key id
    - `secret_access_key` string, required: Secret access key

## Response `200`

The bucket with rotated credentials

- Bucket: Service-level representation of a bucket. Credentials are never returned.
  - `id` string, required: The ID of the bucket
  - `created_at` string, date-time, required: Creation time
  - `updated_at` string, date-time, required: Last update time
  - `name` string, required: Display name
  - `provider` 'aws_s3', required: Object-storage provider backing a bring-your-own bucket.
  - `bucket` string, required: The bucket name
  - `region` string, nullable, required: The bucket region
  - `endpoint_url` string, nullable, required: Custom S3-compatible endpoint
  - `prefix` string, required: Key prefix within the bucket
  - `sse_kms_key_id` string, nullable, required: KMS key id/ARN used to encrypt writes (SSE-KMS)
  - `auth_type` 'assume_role' | 'access_key', required: How omni authenticates against a customer bucket. ASSUME_ROLE is the recommended default for AWS: nothing secret is stored, every service assumes the customer's IAM role via STS on use. ACCESS_KEY remains for S3-compatible providers that have no STS.
  - `role_arn` string, nullable, required: IAM role Mixedbread assumes (auth_type=assume_role); not a secret
  - `external_id` string, nullable, required: sts:ExternalId the role's trust policy must require (auth_type=assume_role); not a secret
  - `status` 'pending' | 'active' | 'error', required: Validation lifecycle of a customer bucket.
  - `last_validated_at` string, date-time, nullable, required: When the bucket was last validated
  - `has_credentials` boolean, required: Whether secret credentials are stored (always false for assume-role buckets)
  - `credentials_version` integer, required: Increments on every credential rotation
  - `object` 'bucket': The type of the object

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/mixedbread/apis/mxbai-omni.md) - [All operations](https://skmtc.dev/mixedbread/apis/mxbai-omni/llms.txt) - [OpenAPI document](https://skmtc.dev/mixedbread/apis/mxbai-omni/revisions/da24b4f7e983?raw)