Request

Response

    Generate Signed S3 Download URL
    GET

    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-fallback query parameter to true, 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
    * Required

    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:
    • true : Returns a single signed OSS URL.
    • false : (Default) Returns multiple signed S3 URLs, where each URL points to a chunk.
    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:
    • true : Returns a URL that points to a CloudFront edge location.
    • false : (Default) Returns a URL that points directly to the S3 object.

    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:
    • complete - The object is ready to be downloaded.
    • chunked - The object was uploaded in chunks, but assembly of chunks into the final object is still pending. Returned when public-resource-fallback = false in the request.
    • fallback - The object was uploaded in chunks, but assembly of chunks into the final object is still pending. Will return an OSS Signed URL instead of a S3 signed URL because public-resource-fallback was set to true in the request.
    • skipped - The server has evaluated an If-None-Match or If-Modified-Since parameter in the request and determined that the cached version of the object is still up-to-date.
    • error - There was an error in the request. Review and verify the requested bucketKey, content-type, and content-disposition before you try again.
    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.
    • Content-Type
    • Content-Disposition
    • Cache-Control.
    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"
    }
    
    Show More

    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
    }
    
    Show More

    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
    }
    
    Show More

    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"
    }
    
    Show More