Bucket Access

Verify Bucket Access

Changed on

Read which principals are CURRENTLY on a SKU's bucket policy.

Read-only: never mutates the policy. One SKU maps to one bucket, so a single call verifies every client on that SKU.

Callers use this to answer "does this client actually have access right now", which no CAMS-side record can answer — the grant ledger and the sample settings rows record what we intended, and a lost concurrent write makes the two disagree.

Two outcomes are deliberately 200s with flags rather than HTTP errors, because the caller must render them as "unknown" and a 4xx/5xx invites a silent fallback to intent instead:

  • bucket_found=false — the SKU or its bucket is not registered.
  • read_ok=false — the live read failed (throttle, access-denied). principal_count is null and present/missing are empty; do NOT read this as "nobody has access".

Defined as sync def on purpose: BucketPolicyManager is fully blocking (boto3 + a sync Postgres handle), so FastAPI runs this in its threadpool rather than stalling the event loop.

post/v2/bucket-access/datasets/{dataset_id}/verify

Request

  • Base URL: https://api.carbonarc.co (the document declares no server; this is the origin it was published from)
  • URL: https://api.carbonarc.co/v2/bucket-access/datasets/{dataset_id}/verify
  • Auth: none declared

Path parameters

dataset_idstring required

Request body

lagstring nullable

Lag of the dataset SKU. Null for the no-lag variant.

cutstring nullable

Cut of the dataset SKU. Null for the no-cut variant.

principal_arnsstring[]

ARNs to check for. Each is reported in present or missing. Pass an empty list to get only principal_count.

Response

Successful Response

dataset_idstring required
lagstring nullable required
cutstring nullable required
bucket_foundboolean required
read_okboolean required
principal_countinteger nullable

Total client-access principals on the live policy. Null when the read failed — NOT zero, which would read as 'nobody has access'.

presentstring[] required
missingstring[] required
read_errorstring nullable

Why the read failed, when read_ok is false: invalid_credentials | no_credentials | access_denied | throttled | bucket_missing | unknown. A fixed vocabulary, never raw AWS text, since the caller renders it and AWS messages can carry bucket names and ARNs.

checked_atstring date-time required

Changes