Restrict S3 credentials and verify access
Limit an S3 credential by permission, protocol, workspace, folder, address, hours and usage, then prove allowed and denied object operations.
Last reviewed
An S3 request must pass every boundary attached to the credential and workspace. The API-key permission limits the operation, Protocols must permit the S3 gateway, the workspace and folder settings restrict location, and the caller’s current workspace role can narrow access further. A successful credential creation does not override a later role or membership change.
Steps
Dosya offers three API-key permissions for S3:
| Permission | Intended S3 use | Operations that are deliberately refused |
|---|---|---|
| Read only | List buckets and objects, inspect metadata, and download objects. | Uploads return API key scope 'read' cannot upload files; delete and copy also require Full access. |
| Upload only | Add new objects without exposing stored content. | Listing returns API key scope 'upload' cannot list files; reads return API key scope 'upload' cannot download files. |
| Full access | Read, upload, copy, move through supported client operations, and delete when the role also permits it. | Role permissions, locks, anchors, usage limits, and workspace policy still apply. |
Deleting an S3 object moves the Dosya file to Trash and returns 204; it does not immediately release storage. The key must have Full access, and the role needs delete_own_files or delete_any_file for the object. Treat aws s3 rm as a destructive action even though recovery may remain available in Trash.
Create a narrowly scoped key
- Sign in at Profile → API keys and select New API key.
- Enter a client-specific label under What is it for? and choose Read only, Upload only, or Full access under What can it do?
- Expand Restrictions and expiry, then open Where can it reach?
- Under Protocols, choose Only the ones I pick and check S3 gateway. Leaving S3 unchecked makes credential activation show Not allowed and the gateway return
This API key is not permitted to use the S3 gateway. - Select the exact Workspace. Choose Folder when the client should see only that folder and its descendants; for an anchored key, the chosen folder becomes the S3 root.
- Add Allowed IP ranges, Only during a weekly window, or limits under How much can it use? when the client has stable requirements. Blank usage fields mean no explicit key limit, while plan and role ceilings can still apply.
- Choose an expiry, review the sentence describing the key, and select Generate key. Save the one-time
dos_value. - Expand the new key. Beside S3 credentials, select Enable and save both
access_key_idandsecret_access_keyfrom the reveal. The secret cannot be retrieved later.
S3 credentials inherit the key’s scope, reach, source conditions, expiry, and usage limits. If credentials already exist, activation returns S3 credentials already exist for this API key. Delete and recreate to regenerate. API keys cannot be edited after creation; use Duplicate settings, create the corrected replacement, test it, and then revoke the old key.


Configure the client
Use the endpoint https://api.dosya.dev/s3, region us-east-1, and the workspace ID as the bucket name. A display name is not a bucket identifier.
export AWS_ACCESS_KEY_ID='REPLACE_WITH_DOSYA_ACCESS_KEY_ID'
read -r -s -p 'S3 secret: ' AWS_SECRET_ACCESS_KEY
printf '\n'
export AWS_SECRET_ACCESS_KEY
DOSYA_WORKSPACE_ID='REPLACE_WITH_WORKSPACE_ID'
aws --endpoint-url https://api.dosya.dev/s3 --region us-east-1 \
s3 ls "s3://$DOSYA_WORKSPACE_ID/"
For a folder-anchored key, paths begin at the selected folder. Do not prepend the folder’s path from the web app, because that would look for a same-named child under the anchor.
Test both sides of the boundary
Use a non-confidential file and commands appropriate to the selected scope:
printf 'S3 permission check\n' > s3-permission-check.txt
# Upload test: suitable for Upload only or Full access.
aws --endpoint-url https://api.dosya.dev/s3 --region us-east-1 \
s3 cp s3-permission-check.txt "s3://$DOSYA_WORKSPACE_ID/tests/s3-permission-check.txt"
# Read test: suitable for Read only or Full access.
aws --endpoint-url https://api.dosya.dev/s3 --region us-east-1 \
s3 cp "s3://$DOSYA_WORKSPACE_ID/tests/s3-permission-check.txt" ./received.txt
Then issue a harmless request that should fail: list with an upload-only key, upload with a read-only key, use another workspace ID with a pinned key, or request a sibling path outside the folder anchor. Expect an S3 XML error with HTTP 403 and AccessDenied. A different-workspace attempt returns This API key is pinned to a different workspace.
The workspace role must include Use the S3 gateway. Object listing also needs file-page access, downloading needs download_files, uploading needs upload_files, and automatically creating missing path folders needs create_folders. Relevant refusals include This role is not permitted to use the S3 gateway, This role cannot list files, Download not allowed, Upload not allowed, and Creating folders is not allowed.
Separate request throttles allow 600 requests per minute per user and 1,200 per minute per IP. The gateway checks explicit key and role request-usage limits before those throttles. A key or role usage refusal returns HTTP 429 with XML SlowDown and Retry-After. The separate request throttles return HTTP 429 with JSON {"ok":false,"error":"Too many requests"} and Retry-After. Read the response reason and honor Retry-After; reduce concurrency for a concurrency refusal. Waiting or replacing a valid credential does not replenish an exhausted byte allowance.
Expiry, anchors, and revocation
An expired API key cannot authenticate or mint S3 credentials. If the selected anchor folder is trashed or removed, requests fail with This API key's anchor folder is no longer available. A member later confined to another folder cannot use a credential anchor outside that permitted subtree.
Revoking the API key stops its bearer token and attached S3 access key from authenticating. Revocation cannot be undone, so update the S3 client with a tested replacement before removing a credential used by a backup or automation. The files already uploaded remain in Dosya; revocation does not delete or recall them.
Expected result
The required operation succeeds inside the chosen bucket and folder, while the planned outside or wrong-scope request returns AccessDenied. The key row identifies its permission, S3 protocol, reach, expiry, and last use, allowing the credential to be audited and revoked independently.
Related guides
Was this helpful?
Loading helpfulness results…
Voting saves a necessary ballot cookie for up to 180 days so you can change your answer.
Questions and replies
Ask about the steps in this guide. Questions are reviewed before publication.
Keep account details, credentials and private files out of public questions. Use private support for those.
Loading questions…
Sign in to your Dosya account to ask a question.