File download tokens usage

A file download token is a one-time-use JWT token that can be sent as a query parameter in a GET request to authenticate/authorize a user to download a non-public file they have access to through the ChRIS REST API. If the token is not used 10 minutes after created then the token expires and cannot be used to download a file. For security reasons once the token is used to download a file it's then automatically revoked.

Create a new file download token with an authenticated POST request

http -a cube:cube1234 POST http://localhost:8000/api/v1/downloadtokens/

HTTP/1.1 201 Created
Allow: GET, POST
Content-Length: 595
Content-Type: application/vnd.collection+json
Cross-Origin-Opener-Policy: same-origin
Date: Mon, 26 Jan 2026 23:25:55 GMT
Location: http://localhost:8000/api/v1/downloadtokens/4/
Referrer-Policy: same-origin
Server: WSGIServer/0.2 CPython/3.12.11
Vary: Accept, origin
X-Content-Type-Options: nosniff
X-Frame-Options: DENY

{
    "collection": {
        "href": "http://localhost:8000/api/v1/downloadtokens/",
        "items": [
            {
                "data": [
                    {
                        "name": "id",
                        "value": 4
                    },
                    {
                        "name": "creation_date",
                        "value": "2026-01-26T18:25:55.851202-05:00"
                    },
                    {
                        "name": "token",
                        "value": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjoiY3ViZSIsIm5vbmNlIjoiMTU4YWE3YzItYjM2Yi00MmY0LWIxZGItOTM3MDU1ZTZiNjI4IiwiZXhwIjoxNzY5NDcwNTU1fQ.e7kfRXO2ZTCFYXKIs7n8KPTwDicmT3REAKqpdrimXwk"
                    },
                    {
                        "name": "owner_username",
                        "value": "cube"
                    }
                ],
                "href": "http://localhost:8000/api/v1/downloadtokens/4/",
                "links": [
                    {
                        "href": "http://localhost:8000/api/v1/users/2/",
                        "rel": "owner"
                    }
                ]
            }
        ],
        "links": [],
        "version": "1.0"
    }
}

Use the token to download a file

Copy the token value from the token field in the previous response and send it as a query parameter to download a non-public file:

http --download http://localhost:8000/api/v1/userfiles/1/welcome.txt download_token==eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjoiY3ViZSIsIm5vbmNlIjoiMTU4YWE3YzItYjM2Yi00MmY0LWIxZGItOTM3MDU1ZTZiNjI4IiwiZXhwIjoxNzY5NDcwNTU1fQ.e7kfRXO2ZTCFYXKIs7n8KPTwDicmT3REAKqpdrimXwk

HTTP/1.1 200 OK
Allow: GET
Content-Disposition: attachment; filename="welcome.txt"
Content-Length: 17
Content-Type: text/plain
Cross-Origin-Opener-Policy: same-origin
Date: Mon, 26 Jan 2026 23:27:05 GMT
Referrer-Policy: same-origin
Server: WSGIServer/0.2 CPython/3.12.11
Vary: origin
X-Content-Type-Options: nosniff
X-Frame-Options: DENY

Downloading to welcome.txt
Done. 17 bytes in 00:0.01900 (894.6818897938393 bytes/s)

Since the token is automatically revoked after used an attempt to reuse it again to download the file will fail:

http --download http://localhost:8000/api/v1/userfiles/1/welcome.txt download_token==eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjoiY3ViZSIsIm5vbmNlIjoiZTVjMzk0YmYtM2QxOC00ODYxLTg0NWQtMmIxNTNmZTEwOTM1IiwiZXhwIjoxNzY5NDY3NjAyfQ.6CT-Wo-htOnVseB3qltXl722zDBw3eTzHigY0NhT1PE

HTTP/1.1 401 Unauthorized
Allow: GET
Content-Length: 6
Content-Type: */*
Cross-Origin-Opener-Policy: same-origin
Date: Mon, 26 Jan 2026 23:27:38 GMT
Referrer-Policy: same-origin
Server: WSGIServer/0.2 CPython/3.12.11
Vary: origin
WWW-Authenticate: Token
X-Content-Type-Options: nosniff
X-Frame-Options: DENY