S3-compatible object storage supports browser-based uploads using an HTML form and HTTP POST request. This method enables a website or web application to upload files directly to a storage Space, without routing the file contents through its own application server.
A browser-based POST upload will usually have a form, an endpoint for storage, and a policy that defines the conditions under which the upload can occur. A trusted application server signs the policy before the form is submitted.
With the S3-compatible API of Cyberin S3 Object Storage, you can integrate file uploads in websites, applications and user-facing upload forms with this approach.
Here is an example of a normal POST upload from a browser:
The browser will ask your application server for permission to upload.
The server creates a policy that describes how the upload should look like (object key, content type, size).
The server signs the policy with the S3 credentials and returns the necessary form fields.
The browser POSTs the file and signed fields to the Space endpoint.
If the signature and policy are correct, the storage service will authenticate the request and store the object.
This lets you write files directly to object storage, while the secret credentials remain on the server.
The upload policy states limitations on the uploaded form. Depending on your application, it may restrict:
The ultimate frontier. Space .
The object key or key prefix that is allowed.
File content type.
The maximum allowed file size.
In the end of the policy.
For example, an application may enable users to upload image files to a particular directory, but restrict the size of the files.
The policy must be encoded and signed according to the S3 compatible POST policy requirements. The application server must return the resulting policy and signature back to the browser.
We use a backend S3 compatible signing implementation to generate the POST policy and signature.
It usually produces form fields that include:
key: The destination object key.
policy: The encoded upload policy.
x-amz-algorithm: The signing algorithm, when using Signature Version 4.
x-amz-credential: The credential scope required for signing.
x-amz-date: The request timestamp.
x-amz-signature: The signature generated by the server.
Depending on the policy and authentication configuration you may need to add additional fields.
The backend should return those values to the browser without exposing the secret access key.
The browser sends the file and server-generated fields as multipart/form-data.
Here is a conceptual html example . Your backend should generate valid values, fill the form fields with values and then submit.
<form
action="https://YOUR_SPACE_NAME.YOUR_REGION.digitaloceanspaces.com"
method="POST"
enctype="multipart/form-data"
>
<input type="hidden" name="key" value="uploads/example.jpg">
<input type="hidden" name="policy" value="SERVER_GENERATED_POLICY">
<input type="hidden" name="x-amz-algorithm" value="AWS4-HMAC-SHA256">
<input type="hidden" name="x-amz-credential" value="SERVER_GENERATED_CREDENTIAL">
<input type="hidden" name="x-amz-date" value="SERVER_GENERATED_TIMESTAMP">
<input type="hidden" name="x-amz-signature" value="SERVER_GENERATED_SIGNATURE">
<input type="file" name="file" required>
<button type="submit">Upload File</button>
</form>Replace endpoint and placeholder values with actual Space endpoint and valid server generated fields. The form fields’ names and values must match the signed policy.
Note: This example only shows the structure of the form. It will not upload a file with placeholder values successfully. Generate a valid policy and signature via your backend’s signing implementation. See current Spaces API support for exact POST policy requirements.
If the website and the storage endpoint are cross-origin the browser may need a proper CORS configuration.
Configure your Space CORS rules to allow the proper website origin, HTTP method, and request headers.
For example, the configuration may have to permit:
Your website's origin.
The POST method.
Any required request headers.
Only allow the origins and methods that your app needs. CORS decides which cross-origin requests from a browser are allowed. It does not substitute authentication and the signed upload policy.
Once you submit the form:
Verify that the upload request was successful.
Check for HTTP success status or error message in response.
Start the Cyberin S3 Object Storage dashboard.
Navigate to the Space and folder where the file should have uploaded to.
Make sure that the object exists and that its name and content are correct.
If the application uses an asynchronous upload flow, only display a success message after the upload has been acknowledged.
Upload returns authentication error: Check policy, signature, credential scope, timestamp and endpoint. The server signs the same policy and conditions that the browser submits.
The policy denies the upload Verify whether the object key, content type, file size and other form fields of the submitted object satisfy the conditions of the policy.
The browser returns a CORS error Check the Space’s CORS configuration and make sure the website origin and required HTTP method are allowed. A CORS error does not necessarily mean that the storage credentials are wrong.
The file does not appear in the Space: Make sure the upload request succeeded and that the form is pointing to the correct Space and regional endpoint.
The secret key is shown in the browser: If the key is compromised , rotate it . Remove it from client side code . Instead, generate the signed policy on the backend.