Storage

Preview — pending review

This reference is generated from the platform API contract and is still under review. Operations, fields, and descriptions can change before publication.

Update the bucket visibility and public-access guardrails (policy statements are refused)

PATCH
/scopes/{scopeId}/storage/buckets/{bucketId}/policies

Updates the bucket's access configuration: the bucket visibility (Private / Public, also driven by the "Make public" / "Make private" header actions) and the block-public-access guardrails (blockPublicAcls, blockPublicPolicy). All fields are optional; omitted fields keep their current value. What the object store enforces. OpenStack Swift enforces one access control on a bucket: its container read ACL. visibility: Public grants anonymous read, Private removes it. Nothing else is accepted, because nothing else would be enforced. Bucket policy documents are not supported. Swift has no bucket-policy engine, so a policyJson that carries statements — or is not a JSON policy object at all — is refused with 422 VALIDATION_FAILED, field: policyJson, details.reason: bucket_policy_not_supported; nothing is stored. A document without statements asks for nothing and is accepted; it replaces the stored document, which is how a document stored before the closure (never enforced) is cleared. Authenticated visibility is not supported. No container ACL is written for it, so visibility: Authenticated is refused with 422 VALIDATION_FAILED, field: visibility, details.reason: authenticated_visibility_not_supported; nothing is stored. Validation: bucketId must reference an existing, non-deleted bucket in the scope (unknown → 404 NOT_FOUND); setting visibility: Public while blockPublicPolicy is (or becomes) true is rejected (→ 409 CONFLICT); caller must hold owner|admin on the scope for public-exposure changes and owner|admin|contributor for the rest, otherwise 403 FORBIDDEN. Async & state: Synchronous — returns 200 with the updated BucketPolicy result; the container read ACL is then reconciled by an objectstore.bucket.policy.update Operation. A resource.updated SSE frame is emitted (kind storage.bucket, patch {visibility, blockPublicAcls, blockPublicPolicy}) so the list view's visibility pill converges. Errors: 401 unauthenticated; 403 caller lacks the required role for the attempted change; 404 unknown scopeId or bucketId; 409 CONFLICT visibility: Public while public policies are blocked; 412 If-Match ETag does not match the current policy revision; 422 unknown visibility value, unsupported policy document or Authenticated visibility; 500 unexpected backend failure. Idempotency/Concurrency: This operation does not use Idempotency-Key; it may be omitted and a sent one is ignored. Every call applies the patch again and queues a new objectstore.bucket.policy.update reconcile Operation; repeating the same patch leaves the same state. If-Match with the ETag from the bucket detail read prevents overwriting a concurrently edited policy.

Authorization

bearerToken
headerAuthorizationBearer <token>

An API token (pc_live_…) or a service-account key (sak_live_…), created in Identity & Access Management and sent as Authorization: Bearer <token>. Requests are rate limited per credential and per tenant: every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a refused request gets 429 RATE_LIMITED with Retry-After.

Path Parameters

scopeId*string

Opaque ownership+authorization scope resolving to tenant + subscription + project.

bucketId*string

Identifier of the bucket.

Header Parameters

If-Match?string

ETag for optimistic concurrency on mutations/deletes; mismatch results in 412.

Request Body

application/json
  1. body

Partial update of the bucket access configuration (omitted fields keep their current value).

policyJson?string

Replacement bucket policy JSON document. Bucket policies are not supported — only a document without statements is accepted; one with statements, or one that is not a JSON policy object, is refused with 422 details.reason: bucket_policy_not_supported.

visibility?string

Private or Public — applied to the container read ACL. Authenticated is refused with 422 details.reason: authenticated_visibility_not_supported.

Value in"Private""Public""Authenticated"
blockPublicAcls?boolean
blockPublicPolicy?boolean

Response Body

The bucket's visibility, public-access guardrails and stored policy document after the change.

application/json
  1. response

The bucket's visibility, public-access guardrails and stored policy document after the change. Only the visibility is enforced (as the container read ACL); the policy document is stored, not enforced.

bucketId*string
policyJson*string

The stored bucket policy document. Not enforced.

visibility*BucketVisibility

Access visibility of a bucket. Authenticated can no longer be set (no container ACL is written for it); a bucket that carries it from before is reported as stored, but the only read ACL ever written for it is the private one.

Value in"Private""Public""Authenticated"
blockPublicAcls*boolean
blockPublicPolicy*boolean
updatedAt*string
Formatdate-time
curl -X PATCH "https://example.com/scopes/string/storage/buckets/string/policies" \  -H "Content-Type: application/json" \  -d '{}'
{  "bucketId": "string",  "policyJson": "string",  "visibility": "Private",  "blockPublicAcls": true,  "blockPublicPolicy": true,  "updatedAt": "2019-08-24T14:15:22Z"}