---
title: "Grant Bucket Access"
method: POST
path: "/v2/bucket-access/datasets/{dataset_id}/grant"
tags: ["Bucket Access"]
---

# Grant Bucket Access

`POST /v2/bucket-access/datasets/{dataset_id}/grant`

Grant a principal access to a dataset's S3 bucket by SKU.

Resolves (dataset_id, lag, cut) → dataset_name via
admin_config.bulk_bucket_details and delegates to
BucketPolicyManager.add_principal_for_sku, which is idempotent.

Compliance gate (runs before any S3 write): the client_name (=clients.key)
must resolve to a clients.id (422 unknown_client otherwise), and the SKU
must not be blocked for that client by the live served-lag restriction
model (403 compliance_blocked otherwise).

## Path parameters

- `dataset_id` string, required

## Request body

- GrantBucketAccessRequest
  - `principal_arn` string, required — IAM principal ARN to grant access to (e.g. 'arn:aws:iam::123456789012:user/alice'), or a 12-digit AWS account id which is converted to '<id>:root'.
  - `client_name` string, required — Client name; must exist in admin_config.clients.
  - `lag` string, nullable — Lag of the dataset SKU to grant access to. Omit (or null) for the no-lag variant — bulk_bucket_details stores no-lag rows with lag=null.
  - `cut` string, nullable — Cut of the dataset SKU to grant access to. Omit (or null) for the no-cut variant — bulk_bucket_details stores no-cut rows with cut=null.

## Response `200`

Successful Response

- GrantBucketAccessResponse
  - `dataset_id` string, required
  - `lag` string, nullable, required
  - `cut` string, nullable, required
  - `principal_arn` string, required
  - `client_name` string, required
  - `granted` boolean, required

## Other responses

- `400` — Malformed principal ARN, or missing required identifier.
- `403` — compliance_blocked: the SKU is restricted for this client.
- `404` — sku_not_found / bucket_not_registered: the SKU has no bucket in admin_config.bulk_bucket_details. Terminal — retrying cannot help.
- `409` — policy_apply_failed / policy_write_race: the bucket-policy write did not land. Transient — the caller should retry.
- `413` — policy_size_exceeded: the bucket policy hit AWS's 20KB limit.
- `422` — unknown_client: client_name is not in admin_config.clients.

---

[API](https://skmtc.net/carbonarc/apis/carbon-arc-api-documentation.md) · [All operations](https://skmtc.net/carbonarc/apis/carbon-arc-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/carbonarc/carbon-arc-api-documentation/revisions/fd615712e250/schema)