Files

POST /v1/stores/{store}/assets/{asset}/url answers where a file's bytes are. A link comes back as it is, and a public file viewed in place as its public URL. A private file, or any file asked for as a download (disposition: "attachment"), comes back as a URL on this API, /v1/stores/{store}/files/..., which answers the bytes to a GET with the same token in the Authorization header: the URL is bound to that token, so another token, or none, cannot fetch it. A token is never taken in the URL: access_token in its query is refused as invalid.

A file shown in place (a video, an image, a document) answers a Range header naming one bytes range with 206 and just those bytes, and If-Range with an earlier ETag answers the whole file once it changed. A range outside the file, or several ranges, answers 416. A download is answered whole and works once, so the route takes no HEAD. The URL serves until expires_at; past it, or once the file changed, ask for a new one. A 403 means the URL is another token's or no longer valid; a 401, the token itself is no longer honored.