oss/v2/buckets/{bucketKey}/objects/{objectKey}/signeds3download
Generates a signed URL to download an object directly from S3, bypassing OSS servers. This signed URL expires in 2 minutes by default, but you can change this duration if needed. You must start the download before the signed URL expires. The download itself can take longer. If the download fails after the validity period of the signed URL has elapsed, you can call this operation again to obtain a fresh signed URL.
Additionally:
- Range headers: You can use range headers with the signed download URL to download the object in chunks, enabling parallel downloads for better performance.
- Multi-part objects: If the object was uploaded in chunks and is still assembling, you’ll receive multiple S3 URLs (one per chunk). To receive a single URL instead, set the
public-resource-fallbackquery parameter totrue, which makes OSS return a single signed OSS URL while assembly is in progress.
OSS offers two types of signed URLs:
- S3 Signed URLs (the type generated by this operation): Enable direct S3 upload/download but are restricted to bucket owners only.
- OSS Signed URLs: Also support upload/download operations and can be configured for access by other applications, making them ideal for sharing objects across different systems.
Important: Only applications with read access to the object can call this operation.
Resource Information
| Method and URI | GET https://developer.api.autodesk.com/oss/v2/buckets/{bucketKey}/objects/{objectKey}/signeds3download |
| Authentication Context | App only |
| Required OAuth Scopes | data:read |
| Data Format | JSON |
Request
Headers
| Authorization* string | Must be Bearer <token>, where <token> is a two-legged access token obtained via a Client Credentials Grant flow. |
| If-None-Match string | The last known sha1 value of the object. OSS returns the signed URL only if the If-None-Match header differs from the sha1 value of the object on S3. If not, it returns a 304 “Not Modified” HTTP status. |
| If-Modified-Since string | A timestamp in the HTTP date format (Mon, DD Month YYYY HH:MM:SS GMT). The signed URL is returned only if the object has been modified since the specified timestamp. If not, a 304 (Not Modified) HTTP status is returned. |
| x-ads-acm-scopes string | Optional OSS-compliant scope reference to increase bucket search performance |
Request
URI Parameters
| bucketKey string | The unique ID of the bucket that contains the objects you are operating on. bucketKey must be URL-encoded. |
| objectKey string | The URL-encoded human friendly name of the object. |
Request
Query String Parameters
| response-content-type string | The value of the Content-Type header you want to receive when you download the object using the signed URL. If you do not specify a value, the Content-Type header defaults to the value stored with OSS. |
| response-content-disposition string | The value of the Content-Disposition header you want to receive when you download the object using the signed URL. If you do not specify a value, the Content-Disposition header defaults to the value stored with OSS. |
| response-cache-control string | The value of the Cache-Control header you want to receive when you download the object using the signed URL. If you do not specify a value, the Cache-Control header defaults to the value stored with OSS. |
| public-resource-fallback boolean | Determines how OSS returns the signed URLs when chunk assembly is not yet complete. Possible values:
|
| minutesExpiration int | The time window (in minutes) the signed URL will remain usable. Acceptable values = 1-60 minutes. Default = 2 minutes.
Tip: Use the smallest possible time window to minimize exposure of the signed URL. |
| useCdn boolean | Determines whether the generated signed URL should use a CloudFront edge location. Possible values:
|
Response
HTTP Status Code Summary
| 200 OK | The signed S3 download URL was successfully generated. |
| 304 Not Modified | The object has not been modified. OSS returns this response when the If-None-Match header matches the sha1 value of the object on S3, or when the object has not been modified since the If-Modified-Since date. |
| 400 Bad Request | The request could not be processed due to missing or malformed parameters. |
| 401 Unauthorized | Invalid authorization header. |
| 403 Forbidden | The request was successfully validated but lacking the required permissions. Verify your credentials and permissions before you send this request again. |
| 404 Not Found | The specified object or bucket does not exist. |
| 500 Internal Server Error | An unexpected error occurred on the server, preventing it from completing your request. Please try again later. If the issue persists, contact the support team for assistance. |
Response
Body Structure (200)
| status enum:string | Indicates the current state of the object requested for download. Possible values are:
|
| url string | A S3 signed URL with which to download the object. This attribute is returned when status is complete or fallback; in the latter case, this will return an OSS signed URL, not an S3 signed URL. |
| urls object | A map of S3 signed URLs, one for each chunk of an unmerged resumable upload. This attribute is returned when status is chunked. The key of each entry is the byte range of the total file which the chunk comprises. |
| params object | The values that were requested for the following parameters when requesting the S3 signed URL.
|
| size int | The total amount of storage space occupied by the object, in bytes. |
| sha1 string | A hash value computed from the data of the object, if available. |
Example 1
Demonstrates the obtaining of an S3 signed URL for an object (raw uploads or merged resumable uploads) (200).
Request
curl
-X GET
-H "Authorization=Bearer eYeL5gYxAT2j3u9TEerxoJoToNbi"
https://developer.api.autodesk.com/oss/v2/buckets/apptestbucket/objects/objectKeyFoo/signeds3download
Response
{
"status": "complete",
"url": "https://oss-bucket-name.s3.amazonaws.com/4F/2D/df/a9f898eda7edee1ab9827cfeb57f2ec647/apptestbucket?response-content-disposition=attachment%3B%20filename%3D%22objectKeyFoo%22&response-content-type=application%2Foctet-stream&X-Amz-Security-Token=AWS_TOKEN&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210120T152914Z&X-Amz-SignedHeaders=host&X-Amz-Expires=120&X-Amz-Credential=[AMZ CREDENTIAL]&X-Amz-Signature=6c1abf52e7849asignature",
"params" : {
"content-type": "application/octet-stream",
"content-disposition": "attachment; filename=\"objectKeyFoo\""
},
"size" : 221983,
"sha1" : "4F2Ddfa9f898eda7edee1ab9827cfeb57f2ec647"
}
Example 2
Demonstrates the obtaining an OSS signed URL for an unmerged object because public-resource-fallback equals to true (200).
Request
curl
-X GET
-H "Authorization=Bearer eYeL5gYxAT2j3u9TEerxoJoToNbi"
https://developer.api.autodesk.com/oss/v2/buckets/apptestbucket/objects/unmerged.json/signeds3download?public-resource-fallback=true
Response
{
"status": "fallback",
"url": "http://developer.api.autodesk.com/oss/v2/signedresources/6969f2ed-2931-498f-bad8-b9d300ad1c7e?region=US",
"params" : {
"content-type": "application/json",
"content-disposition": "attachment; filename=\"unmerged.json\""
},
"size" : 19715187
}
Example 3
Demonstrates the obtaining of multiple S3 signed URLs for an unmerged object, one per chunk (200).
Request
curl
-X GET
-H "Authorization=Bearer eYeL5gYxAT2j3u9TEerxoJoToNbi"
https://developer.api.autodesk.com/oss/v2/buckets/apptestbucket/objects/unmerged.json/signeds3download
Response
{
"status": "chunked",
"urls": {
"0-10747471": "https://oss-bucket.s3.amazonaws.com/ead4b508f5a502b9251d16b640128ad83af7e4ba/bucket/apptestbucket/chunk-uuid/uuid-fcdf6275-8789-472f-b811-5472c9262ffc?response-content-disposition=attachment%3B%20filename%3D%22unmerged.json%22&response-content-type=application%2Fjson&X-Amz-Security-Token=AWS_TOKEN&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210120T152914Z&X-Amz-SignedHeaders=host&X-Amz-Expires=120&X-Amz-Credential=[AMZ CREDENTIAL]&X-Amz-Signature=6c1abf52e7849asignature",
"10747472-19715186": "https://oss-bucket.s3.amazonaws.com/ead4b508f5a502b9251d16b640128ad83af7e4ba/bucket/apptestbucket/chunk-uuid/uuid-cc685997-7afa-4dd3-ada3-71390a973bc5?response-content-disposition=attachment%3B%20filename%3D%22unmerged.json%22&response-content-type=application%2Fjson&X-Amz-Security-Token=AWS_TOKEN&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210120T152914Z&X-Amz-SignedHeaders=host&X-Amz-Expires=120&X-Amz-Credential=[AMZ CREDENTIAL]&X-Amz-Signature=6c1abf52e7849asignature"
},
"params" : {
"content-type": "application/json",
"content-disposition": "attachment; filename=\"unmerged.json\""
},
"size" : 19715187
}
Example 4
Demonstrates the obtaining of an S3 signed URL for an object using the minutesExpiration parameter (200).
Request
curl
-X GET
-H "Authorization=Bearer eYeL5gYxAT2j3u9TEerxoJoToNbi"
https://developer.api.autodesk.com/oss/v2/buckets/apptestbucket/objects/objectKeyFoo/signeds3download?minutesExpiration=30
Response
{
"status": "complete",
"url": "https://oss-bucket-name.s3.amazonaws.com/4F/2D/df/a9f898eda7edee1ab9827cfeb57f2ec647/apptestbucket?response-content-disposition=attachment%3B%20filename%3D%22objectKeyFoo%22&response-content-type=application%2Foctet-stream&X-Amz-Security-Token=AWS_TOKEN&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210120T152914Z&X-Amz-SignedHeaders=host&X-Amz-Expires=1800&X-Amz-Credential=[AMZ CREDENTIAL]&X-Amz-Signature=6c1abf52e7849asignature",
"params" : {
"content-type": "application/octet-stream",
"content-disposition": "attachment; filename=\"objectKeyFoo\""
},
"size" : 221983,
"sha1" : "4F2Ddfa9f898eda7edee1ab9827cfeb57f2ec647"
}