# How to create and modify an Object Storage bucket

import DocButton from '~/components/webkit/DocButton.vue';
import Tabs from '~/components/tabs/Tabs'

Azion **Object Storage** lets you create buckets and integrate your object storage with your edge infrastructure. This guide covers how to create, update, and delete a storage bucket using the [Azion API](https://api.azion.com).

By creating a native bucket on Azion, you ensure your data resides on the same global network infrastructure that processes your requests, eliminating fetch latency from external providers and ensuring **zero Data Transfer Out (DTO)** cost.

<DocButton href="/en/documentation/products/store/object-storage/" label="learn more about Object Storage" kind="secondary" size="medium" />

Refer to the guide [How to upload and download objects from a bucket](/pt-br/documentacao/produtos/guias/upload-e-download-de-objetos-do-bucket/) to perform object operations.

---

<Tabs client:visible>
    <Fragment slot="tab.api">API</Fragment>
    <Fragment slot="tab.console">Console</Fragment>

<Fragment slot="panel.api">

## Create a read-only bucket

Run the following `POST` request in your terminal, replacing `[TOKEN VALUE]` with your [personal token](/pt-br/documentacao/produtos/guias/personal-tokens/) and the `name` value with the bucket name to create a new read-only bucket:

```bash
curl --location 'https://api.azion.com/v4/storage/buckets' \
--header 'Accept: application/json; version=3' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token [TOKEN VALUE]' \
--data '{
    "name": "my-bucket-ro",
    "edge_access": "read_only"
}'
```

You should receive the following response:

```json
{
  "state": "executed",
  "data": {
    "name": "my-bucket-ro",
    "edge_access": "read_only"
  }
}
```

Now you can use the bucket to [upload and download objects](/pt-br/documentacao/produtos/guias/upload-e-download-de-objetos-do-bucket/).

---

## Grant read-write permission to a bucket

Run the following `PATCH` request in your terminal, replacing `[TOKEN VALUE]` with your [personal token](/pt-br/documentacao/produtos/guias/personal-tokens/) and `bucket_name` with the bucket name to grant read and write permissions:

```bash
curl --location 'https://api.azion.com/v4/storage/buckets/<bucket_name>' \
--header 'Accept: application/json; version=3' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token [TOKEN VALUE]' \
--data '{
    "edge_access": "read_write"
}'
```

You should receive the following response:

```json
{
  "state": "executed",
  "data": {
    "name": "my-bucket-ro",
    "edge_access": "read_write"
  }
}
```

</Fragment>

<Fragment slot="panel.console">

To create your first bucket via the [Azion Console](https://console.azion.com):

1. In the upper-left menu, select **Object Storage**.
2. Click the **+ Bucket** button.
3. **Bucket Name:** Set a unique name (between 6 and 63 characters).
    * *Tip: Use names that describe the purpose, such as `media-assets-prod`.*
4. **Workloads Access:** Choose how the Azion platform will interact with your data:
    * **Read Only:** Recommended for serving static content (HTML, images). The Edge can read but not modify.
    * **Read-Write:** Allows Edge applications (Functions) to read and write files to the bucket.
    * **Restricted:** Blocks direct access from the Azion Web Platform; access will only be allowed via API or the S3 Protocol.
5. Click **Save**.

</Fragment>
</Tabs>

:::caution[Warning]
When a bucket is configured with **read-write permissions**, any user can access and modify its content (for example, by sending a PUT request to overwrite files). If the bucket is used as an origin for an application, this setting can expose content to unauthorized changes. However, if the bucket is accessed through a function, the risk is managed by the logic implemented in the function code, allowing developers to enforce stricter controls over who can access or modify the data. To mitigate risks, always verify the permissions required for each use case and implement appropriate access controls. Learn more about [Authentication and permissions](/pt-br/documentacao/produtos/gestao-de-contas/teams-permissions/).
:::

---

## Delete a bucket

Run the following `DELETE` request in your terminal, replacing `[TOKEN VALUE]` with your [personal token](/pt-br/documentacao/produtos/guias/personal-tokens/) and `bucket_name` with the name of the bucket you want to delete:

<Tabs client:visible>
    <Fragment slot="tab.api">API</Fragment>
    <Fragment slot="tab.console">Console</Fragment>

<Fragment slot="panel.api">

```bash
curl --location --request DELETE 'https://api.azion.com/v4/storage/buckets/<bucket_name>' \
--header 'Accept: application/json' \
--header 'Authorization: Token [TOKEN VALUE]'
```

</Fragment>

<Fragment slot="panel.console">

You can adjust permissions or remove buckets as your application evolves.

### Change permissions

1. In the bucket list, click the name of the desired bucket.
2. Change the **Access** level.
3. Click **Save**.

### Delete a bucket

:::caution[Warning]
To delete a bucket, it must be completely empty. If you removed the last object recently, wait the **24-hour** period for the bucket deletion to be processed by the system.
:::

1. Make sure there are no objects in the bucket.
2. In the bucket list, click the trash icon or select the bucket and click **Delete**.

</Fragment>
</Tabs>

:::note
This operation can only be performed if the bucket is empty.
:::