# Limit a key to one bucket

Create an access key that can only read, or read and write, the objects of one bucket or one prefix, through S3 and the API alike.

A key with a scope policy can do only what both its IAM user and the scope allow, through S3 and
through the API alike. A bucket policy does not widen it, and a `Deny` in the scope always wins.
Replace _example-uploads_ with your bucket's name and _org-EXAMPLE1234_ with your organization's id.

## Prerequisites

- Permission for `iam:CreateAccessKey`. Without it the bucket page has no **Create access key**
  button.
- The IAM user the key acts as may already do what the scope allows: the scope only narrows.

## Create the key

**Console**
1. Open **Object Storage**, open the bucket, then choose **Create access key**. The **Create
   access key for example-uploads** sheet opens with **Acts as** set to you, **Description** set
   to `example-uploads access`, **Limited to** set to **One bucket**, the bucket chosen, and
   **Access** set to **Read and write**.
2. (Optional) For **Access**, choose **Read only**.
3. (Optional) For **Folder (prefix)**, enter a prefix, for example `incoming/` (no `*`). Listing
   still shows every object name in the bucket.
4. (Optional) Under **Expiry**, for **Expires after (days)**, enter how long the key lives. It
   starts on your organization's default and cannot exceed its maximum.
5. Choose **Create access key**.
6. Copy the **Key ID** and the **Secret**. This is the only time the secret is shown.

The panel shows an **AWS CLI profile** for the key and how to use it.

**CLI**
```sh
dcloud iam access-keys create --description "uploads app" --scope-policy '{
  "Version": "2024-01-01",
  "Statement": [{
    "Effect": "Allow",
    "Action": ["s3:ListObjects", "s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
    "Resource": ["rn:ews::org-EXAMPLE1234:s3:bucket/example-uploads", "rn:ews::org-EXAMPLE1234:s3:bucket/example-uploads/object/*"]
  }]
}'
```

**API**
```http
POST /iam/api/access-keys
{ "description": "uploads app", "scopePolicy": "{\"Version\":\"2024-01-01\",\"Statement\":[{\"Effect\":\"Allow\",\"Action\":[\"s3:ListObjects\",\"s3:GetObject\"],\"Resource\":[\"rn:ews::org-EXAMPLE1234:s3:bucket/example-uploads\",\"rn:ews::org-EXAMPLE1234:s3:bucket/example-uploads/object/*\"]}]}" }
```

**Terraform**
```hcl
resource "dcloud_iam_access_key" "uploads" {
  description = "uploads app"
  scope_policy = jsonencode({
    Version = "2024-01-01"
    Statement = [{
      Effect   = "Allow"
      Action   = ["s3:ListObjects", "s3:GetObject"]
      Resource = ["rn:ews::org-EXAMPLE1234:s3:bucket/example-uploads", "rn:ews::org-EXAMPLE1234:s3:bucket/example-uploads/object/*"]
    }]
  })
}
```

For one prefix, end the object resource with it:
`rn:ews::org-EXAMPLE1234:s3:bucket/example-uploads/object/incoming/*`.

## What the console's scope grants

| Access         | On the bucket                                                                       | On its objects (or the prefix)                                                              |
| -------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| Read only      | `s3:GetBucket`, `s3:ListObjects`, `s3:ListBucketVersions`, `s3:GetBucketVersioning` | `s3:GetObject`, `s3:GetObjectVersion`                                                       |
| Read and write | the same                                                                            | also `s3:PutObject`, `s3:DeleteObject`, `s3:AbortMultipartUpload`, `s3:DeleteObjectVersion` |

`s3:GetBucketVersioning` lets tools such as rclone read the bucket's versioning status before a
purge.

## Using the key

A key limited to one bucket cannot list your buckets: `aws s3 ls` answers `AccessDenied`. Name the
bucket in every command (`aws s3 ls s3://example-uploads/`), and in tools that start from a bucket
list (Cyberduck, S3 Browser), type the bucket in as the path.

## Related

- [Create an access key](create-an-access-key.md)
- [Access control](access-control.md)
- `dcloud iam access-keys create` · `dcloud_iam_access_key`
