--- name: azion-use-s3-compatible-tools-with-object-storage description: >- Create an S3 credential for Object Storage, configure s3cmd or an SDK with it, and manage the objects of your buckets from the tools you already run. --- # Use S3-compatible tools with Object Storage [Object Storage](/en/documentation/platform/object-storage/) answers the S3 protocol, so you manage objects with the tools you already run, such as s3cmd and the boto3 library. Each tool authenticates with an S3 credential, and then lists, uploads, downloads, and deletes the objects of the buckets that credential reaches. --- ## Prerequisites - A bucket for the credential to reach. Refer to [Create a bucket](/en/documentation/guides/application-development/data/create-and-modify-bucket/). - Access to Azion Console, for the Console procedure. Refer to [Access Azion Console](/en/documentation/guides/platform/account-and-billing/how-to-access-azion-console/). - A [personal token](/en/documentation/guides/platform/account-and-billing/personal-tokens/), for the API procedure. - An S3 client: s3cmd for the command-line procedures, or Python with the boto3 library for the SDK example. --- ## Create a credential in Azion Console A credential carries a set of capabilities, and each capability is one checkbox on the create form. | Console label | API value | What the credential may do | | ------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------ | | **List Files** | `listFiles` | View the files stored in the bucket: `ListObjects` and `ListObjectsV2`. | | **Read Files** | `readFiles` | Access and download files: `GetObject` and `HeadObject`. | | **Write Files** | `writeFiles` | Upload or modify files: `PutObject`, `CopyObject`, `CreateMultipartUpload`, `UploadPart`, and `CompleteMultipartUpload`. | | **Delete Files** | `deleteFiles` | Remove files: `DeleteObject`, `DeleteObjects`, and `AbortMultipartUpload`. It requires **Write Files**. | | **List All Bucket Names** | `listAllBucketNames` | Retrieve the names of the available buckets: `ListBuckets`. | | **List Buckets** | `listBuckets` | View bucket details, including metadata and configurations: `HeadBucket`, `ListMultipartUploads`, and `ListParts`. | To create the credential: 1. **Open Object Storage in Azion Console** Access [Azion Console](https://console.azion.com/) > **Object Storage**. 2. **Start the credential** Select **Create Credential**, the control that configures a new credential to reach your Object Storage bucket. 3. **Name the credential** Under **General**, in **Name**, enter a name that says what uses the credential, such as `ci-upload`. 4. **Set the expiration date** Enter the date on which the credential stops working. 5. **Select the capabilities** Select one checkbox per operation the credential allows, from the six in the table above. 6. **Copy the secret key** Azion Console reports "Credential has been created" and shows the secret key once, in a copy dialog. Copy the secret key before you close the dialog. The credential exists in your account, and you hold the only copy of its secret key. --- ## Create a credential using the API `POST /v4/workspace/storage/credentials` creates the credential and returns the key pair. The body accepts four fields: | Field | Required | What it sets | | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `name` | Yes | Identifies the credential in your account. | | `capabilities` | Yes | The operations the credential allows: `listFiles`, `readFiles`, `writeFiles`, `deleteFiles`, `listAllBucketNames`, and `listBuckets`. | | `buckets` | No | An array of bucket names the credential reaches. Omit the field and the credential reaches every bucket in the account. | | `expiration_date` | No | The moment the credential stops working, in UTC ISO 8601. The field is `null` when you omit it. | The field is the plural `buckets`, and it takes an array. A singular `bucket` field is accepted and ignored, and the credential it creates reaches the whole account. For the S3 operations each capability covers, refer to [S3 compatibility](/en/documentation/platform/object-storage/s3-compatibility/). To create the credential: 1. **Send the create request** Replace `[TOKEN VALUE]` with your personal token, and `my-static-bucket` with the bucket the credential reaches: ```bash curl --request POST \ --url https://api.azion.com/v4/workspace/storage/credentials \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: application/json' \ --data '{ "name": "full-access", "capabilities": [ "listFiles", "readFiles", "writeFiles", "deleteFiles", "listAllBucketNames", "listBuckets" ], "buckets": [ "my-static-bucket" ], "expiration_date": "2026-12-31T23:59:59Z" }' ``` 2. **Read the response** A `201` carries the credential, with the access key and the secret key your S3 client needs: ```json { "state": "executed", "data": { "id": 1234, "name": "full-access", "access_key": "[ACCESS KEY]", "secret_key": "[SECRET KEY]", "capabilities": [ "listFiles", "readFiles", "writeFiles", "deleteFiles", "listAllBucketNames", "listBuckets" ], "buckets": [ "my-static-bucket" ], "expiration_date": "2026-12-31T23:59:59Z", "last_editor": "user@example.com", "created_at": "2026-01-01T12:00:00.000000Z", "last_modified": "2026-01-01T12:00:00.000000Z" } } ``` 3. **Save the key pair** Copy `data.access_key` and `data.secret_key` into the tool you configure next. The credential reaches the buckets in `data.buckets`, and `DELETE /v4/workspace/storage/credentials/{id}` removes it. > **Caution** > > This call is the only one that returns `secret_key`. Azion cannot recover it, and a later `GET` on the credentials endpoint never returns it. Replace a lost secret key by creating another credential. --- ## Configure s3cmd [s3cmd](https://s3tools.org/s3cmd) is a command-line tool for S3 and other cloud storage services, and `s3cmd --configure` asks for each connection setting in turn. To configure it: 1. **Install s3cmd** Install the s3cmd package on the machine that manages the objects. 2. **Add s3cmd to your PATH** Confirm that your system PATH holds `s3cmd`, so the command runs from any directory. 3. **Start the configuration** ```bash s3cmd --configure ``` 4. **Enter the access key and the secret key** Enter the `access_key` and the `secret_key` of the credential you created. 5. **Enter the region** Enter `us-east-005`, the region the Object Storage endpoint is named for. 6. **Enter the endpoint** Enter `s3.us-east-005.azionstorage.net`. 7. **Enter the DNS template** Enter `%(bucket).s3.us-east-005.azionstorage.net`, which addresses each bucket as a subdomain of the endpoint. 8. **(Optional) Enter an encryption password** Enter an encryption password and the path to your GPG program. Gnu Privacy Guard is free and open-source encryption software, and it adds a layer of cryptographic privacy and authentication to the S3 communication. 9. **Turn on HTTPS** Enter `true`. 10. **(Optional) Enter an HTTP proxy server** Leave the answer blank when your machine connects directly. 11. **Press y to test the settings** s3cmd signs a request with the keys you entered and reports the result: ```text Please wait, attempting to list all buckets... Success. Your access key and secret key worked fine :-) ``` s3cmd now reaches your buckets with that credential. You can save the answers into an `.s3cfg` file, and run `s3cmd --configure` again to change them. --- ## Manage objects with s3cmd Every command addresses a bucket or an object by its `s3://` URL. | Command | What it does | | ---------------------------------------------- | ---------------------------------------------------------------------------- | | `s3cmd ls` | Lists every bucket in the account. | | `s3cmd ls s3://my-bucket` | Lists the contents of the bucket. | | `s3cmd put file.xml s3://my-bucket/file.xml` | Uploads a file into the bucket. | | `s3cmd get s3://my-bucket/file.xml file-2.xml` | Downloads the object into a local file, which you compare with the original. | | `s3cmd del s3://my-bucket/addrbook.xml` | Deletes an object. | | `s3cmd info s3://my-bucket/file.xml` | Returns the metadata of an object without downloading it. | > **Caution** > > The S3 endpoint manages objects, not buckets. `s3cmd mb` and `s3cmd rb` are refused with `403 AccessDenied` and the message `not entitled`, whatever capabilities the credential carries. Create and delete buckets from Azion Console, the Azion API, or the Azion CLI, as [Create a bucket](/en/documentation/guides/application-development/data/create-and-modify-bucket/) covers. Run `s3cmd --help` to list every command the tool accepts. --- ## Connect with an SDK Any S3 SDK reaches the same endpoint with the same credential. boto3 is the library most Python projects use for S3 storage, and its client takes the endpoint, the region, and the key pair: ```python import boto3 s3 = boto3.client( "s3", endpoint_url="https://s3.us-east-005.azionstorage.net", aws_access_key_id="[ACCESS KEY]", aws_secret_access_key="[SECRET KEY]", region_name="us-east-005", ) response = s3.list_objects_v2(Bucket="my-static-bucket") for obj in response.get("Contents", []): print(f"Object found: {obj['Key']}") ``` The script prints one line per object stored in the bucket: ```text Object found: images/logo.png ``` The endpoint signs requests with SigV4, and it also answers a path-style address, `s3.us-east-005.azionstorage.net//`. It serves object management, not delivery to end users: an application backed by a connector is what answers a request from the internet. --- ## Next steps - [S3 compatibility](/en/documentation/platform/object-storage/s3-compatibility.md): Every capability, the S3 operations Azion answers, and what the endpoint returns. - [Upload and download objects](/en/documentation/guides/application-development/data/upload-and-download-objects-from-bucket.md): Move the same objects with the Azion API and the Azion CLI. - [Create a bucket](/en/documentation/guides/application-development/data/create-and-modify-bucket.md): Create the bucket a credential reaches, and set the access level the platform uses. - [Use a bucket as an application origin](/en/documentation/guides/application-development/data/use-bucket-as-origin.md): Serve the objects to the public, which the S3 endpoint does not do.