The authos says a "File download API can be tricky to implement", but doesn't elaborate as to why.

Any suggestions as to why this may be?

It's pretty hard/near impossible to return a file via an XHR/AJAX response. Traditionally a web-browser would just open the URL to which the file would be downloaded from, which makes JWT authentication tricky as you can't pass custom headers on this type of request (and thus your request can't be authenticated/trusted).

Our workaround for this was to have our filter also look the JWT in a query parameter on the URL.

Like @awzurn already explained, in the absence cookies one would need to to pass token through the URL (Signed URL).

Ideally, that token would contain only permission to download that specific file for certain period of time. That said, one additional filter would have to be implemented to look for token in the URL.

I believe that Amazon S3 is doing the same with signing URL requests for file download (http://docs.aws.amazon.com/AmazonCloudFront/latest/Developer... and http://docs.aws.amazon.com/AmazonS3/latest/dev/RESTAuthentic...)

If you don't mind downloading the whole file into the browsers memory this should do:

https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequ... https://developer.mozilla.org/en-US/docs/Web/API/URL/createO...

And then programmatically click the object URL.

Random idea: inject invisible img element and return the src in the Ajax element. Then grab the downloaded image directly from the div?

That sounds like you leak JWTs into your log files