From a660fa67bca32213397e65978df917d748955b73 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pallinger=20P=C3=A9ter?= Date: Tue, 3 Feb 2026 17:25:43 +0100 Subject: [PATCH 1/6] document preview URL token usage as API key --- doc/sphinx-guides/source/api/auth.rst | 18 ++++++++++++++++++ doc/sphinx-guides/source/api/native-api.rst | 13 +++++++++++++ 2 files changed, 31 insertions(+) diff --git a/doc/sphinx-guides/source/api/auth.rst b/doc/sphinx-guides/source/api/auth.rst index 8dffb914e29..2d0d85d3eb6 100644 --- a/doc/sphinx-guides/source/api/auth.rst +++ b/doc/sphinx-guides/source/api/auth.rst @@ -66,6 +66,24 @@ You can reset your API Token from your account page in your Dataverse installati .. _bearer-tokens: +Using Preview URL tokens as API Token +------------------------------------- + +If you want to access a dataset's contents shared by a preview URL (see :ref:`preview-url-to-review-unpublished-dataset`, :ref:`get-dataset-by-preview-url-token` and :ref:`create-a-preview-url-for-a-dataset`) using the API, you can use the token in the preview URL as API_TOKEN. + +.. code-block:: bash + + SERVER_URL=https://demo.dataverse.org + PREVIEW_URL_TOKEN=a56444bc-7697-4711-8964-e0577f055fd2 + + # this gets you the file listing with the corresponding file IDs, file names and other file metadata + curl "$SERVER_URL/api/datasets/privateUrlDatasetVersion/$PREVIEW_URL_TOKEN" + + # this gets you a specific file + FILE_ID=1111111 + FILENAME=example.txt + curl -H "X-Dataverse-key:$PREVIEW_URL_TOKEN" -o "$FILENAME" "$SERVER_URL/api/access/datafile/$FILE_ID" + Bearer Tokens ------------- diff --git a/doc/sphinx-guides/source/api/native-api.rst b/doc/sphinx-guides/source/api/native-api.rst index 20ff079f5a3..344493969e8 100644 --- a/doc/sphinx-guides/source/api/native-api.rst +++ b/doc/sphinx-guides/source/api/native-api.rst @@ -3997,6 +3997,19 @@ Get Citation by Preview URL Token curl "$SERVER_URL/api/datasets/previewUrlDatasetVersion/$PREVIEW_URL_TOKEN/citation" +Get Files Using Preview URL Token +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you want to access a dataset's contents shared by a preview URL (see :ref:`preview-url-to-review-unpublished-dataset`, :ref:`get-dataset-by-preview-url-token` and :ref:`create-a-preview-url-for-a-dataset`) using the API, you can use the token in the preview URL as API_TOKEN. + +.. code-block:: bash + + SERVER_URL=https://demo.dataverse.org + PREVIEW_URL_TOKEN=a56444bc-7697-4711-8964-e0577f055fd2 + FILE_ID=1111111 + FILENAME=example.txt + curl -H "X-Dataverse-key:$PREVIEW_URL_TOKEN" -o "$FILENAME" "$SERVER_URL/api/access/datafile/$FILE_ID" + .. _get-dataset-summary-field-names: Get Summary Field Names From 7e4a074d625f1415afe80a6f2869398dd14073c2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pallinger=20P=C3=A9ter?= Date: Wed, 4 Feb 2026 09:01:10 +0100 Subject: [PATCH 2/6] fix refenences for preview-url-token-as-api-token documentation --- doc/sphinx-guides/source/api/auth.rst | 2 +- doc/sphinx-guides/source/api/native-api.rst | 9 ++++++++- 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/doc/sphinx-guides/source/api/auth.rst b/doc/sphinx-guides/source/api/auth.rst index 2d0d85d3eb6..0b5a90a4010 100644 --- a/doc/sphinx-guides/source/api/auth.rst +++ b/doc/sphinx-guides/source/api/auth.rst @@ -69,7 +69,7 @@ You can reset your API Token from your account page in your Dataverse installati Using Preview URL tokens as API Token ------------------------------------- -If you want to access a dataset's contents shared by a preview URL (see :ref:`preview-url-to-review-unpublished-dataset`, :ref:`get-dataset-by-preview-url-token` and :ref:`create-a-preview-url-for-a-dataset`) using the API, you can use the token in the preview URL as API_TOKEN. +If you want to access a dataset's contents shared by a preview URL (see :ref:`previewUrl`, :ref:`get-files-using-preview-url-token`, :ref:`get-dataset-by-preview-url-token` and :ref:`create-a-preview-url-for-a-dataset`) using the API, you can use the token in the preview URL as API_TOKEN. .. code-block:: bash diff --git a/doc/sphinx-guides/source/api/native-api.rst b/doc/sphinx-guides/source/api/native-api.rst index 344493969e8..1568c2bca5b 100644 --- a/doc/sphinx-guides/source/api/native-api.rst +++ b/doc/sphinx-guides/source/api/native-api.rst @@ -2808,6 +2808,8 @@ The fully expanded example above (without environment variables) looks like this curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X DELETE "https://demo.dataverse.org/api/datasets/2347/assignments/6" +.. _create-a-preview-url-for-a-dataset: + Create a Preview URL for a Dataset ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -3914,6 +3916,8 @@ Like :ref:`get-export-formats`, this API can be used to get URLs to dataset meta curl -H "Accept:application/json" "$SERVER_URL/api/datasets/:persistentId/versions/$VERSION/linkset?persistentId=$PERSISTENT_IDENTIFIER" +.. _get-dataset-by-preview-url-token: + Get Dataset By Preview URL Token ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -3997,10 +4001,13 @@ Get Citation by Preview URL Token curl "$SERVER_URL/api/datasets/previewUrlDatasetVersion/$PREVIEW_URL_TOKEN/citation" + +.. _get-files-using-preview-url-token: + Get Files Using Preview URL Token ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you want to access a dataset's contents shared by a preview URL (see :ref:`preview-url-to-review-unpublished-dataset`, :ref:`get-dataset-by-preview-url-token` and :ref:`create-a-preview-url-for-a-dataset`) using the API, you can use the token in the preview URL as API_TOKEN. +If you want to access a dataset's contents shared by a preview URL (see :ref:`previewUrl`, :ref:`get-dataset-by-preview-url-token` and :ref:`create-a-preview-url-for-a-dataset`) using the API, you can use the token in the preview URL as API_TOKEN. .. code-block:: bash From b866164c9e64af4d6edcd02a51e5457fb6d7cf80 Mon Sep 17 00:00:00 2001 From: pallinger <1242914+pallinger@users.noreply.github.com> Date: Thu, 5 Feb 2026 08:57:27 +0100 Subject: [PATCH 3/6] Update doc/sphinx-guides/source/api/auth.rst Co-authored-by: Philip Durbin --- doc/sphinx-guides/source/api/auth.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/sphinx-guides/source/api/auth.rst b/doc/sphinx-guides/source/api/auth.rst index 0b5a90a4010..d470d4a596a 100644 --- a/doc/sphinx-guides/source/api/auth.rst +++ b/doc/sphinx-guides/source/api/auth.rst @@ -66,8 +66,8 @@ You can reset your API Token from your account page in your Dataverse installati .. _bearer-tokens: -Using Preview URL tokens as API Token -------------------------------------- +Using Preview URL Tokens as API Token +-------------------------------------- If you want to access a dataset's contents shared by a preview URL (see :ref:`previewUrl`, :ref:`get-files-using-preview-url-token`, :ref:`get-dataset-by-preview-url-token` and :ref:`create-a-preview-url-for-a-dataset`) using the API, you can use the token in the preview URL as API_TOKEN. From 2252bcbbd0fe3ef36e62240b61824b6076cd1dfd Mon Sep 17 00:00:00 2001 From: pallinger <1242914+pallinger@users.noreply.github.com> Date: Thu, 5 Feb 2026 08:57:51 +0100 Subject: [PATCH 4/6] Update doc/sphinx-guides/source/api/native-api.rst Co-authored-by: Philip Durbin --- doc/sphinx-guides/source/api/native-api.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/sphinx-guides/source/api/native-api.rst b/doc/sphinx-guides/source/api/native-api.rst index 51d555d2d30..6dd08c14c09 100644 --- a/doc/sphinx-guides/source/api/native-api.rst +++ b/doc/sphinx-guides/source/api/native-api.rst @@ -4004,8 +4004,8 @@ Get Citation by Preview URL Token .. _get-files-using-preview-url-token: -Get Files Using Preview URL Token -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Get Files Using a Preview URL Token +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you want to access a dataset's contents shared by a preview URL (see :ref:`previewUrl`, :ref:`get-dataset-by-preview-url-token` and :ref:`create-a-preview-url-for-a-dataset`) using the API, you can use the token in the preview URL as API_TOKEN. From e1eb6c13ca9116e9bbf8fc7d8e29203ba6f6663b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pallinger=20P=C3=A9ter?= Date: Thu, 5 Feb 2026 09:26:36 +0100 Subject: [PATCH 5/6] moved preview-url-token-as-api-token documenation to Data Access API doc from Native API doc --- doc/sphinx-guides/source/api/dataaccess.rst | 17 +++++++++++++++++ doc/sphinx-guides/source/api/native-api.rst | 17 ++--------------- 2 files changed, 19 insertions(+), 15 deletions(-) diff --git a/doc/sphinx-guides/source/api/dataaccess.rst b/doc/sphinx-guides/source/api/dataaccess.rst index 0782665776d..b8b103b76ed 100755 --- a/doc/sphinx-guides/source/api/dataaccess.rst +++ b/doc/sphinx-guides/source/api/dataaccess.rst @@ -168,6 +168,23 @@ The fully expanded example above (without environment variables) looks like this curl -H "Range:bytes=0-9" https://demo.dataverse.org/api/access/datafile/42 + +.. _get-file-using-preview-url-token: + +Using a Preview URL Token +~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you want to access a file in a dataset shared by a preview URL (see :ref:`previewUrl`, :ref:`get-dataset-by-preview-url-token` and :ref:`create-a-preview-url-for-a-dataset`) using the API, you can use the token in the preview URL as API_TOKEN. + +.. code-block:: bash + + SERVER_URL=https://demo.dataverse.org + PREVIEW_URL_TOKEN=a56444bc-7697-4711-8964-e0577f055fd2 + FILE_ID=1111111 + FILENAME=example.txt + curl -H "X-Dataverse-key:$PREVIEW_URL_TOKEN" -o "$FILENAME" "$SERVER_URL/api/access/datafile/$FILE_ID" + + Multiple File ("bundle") download --------------------------------- diff --git a/doc/sphinx-guides/source/api/native-api.rst b/doc/sphinx-guides/source/api/native-api.rst index 6dd08c14c09..6f382b47c57 100644 --- a/doc/sphinx-guides/source/api/native-api.rst +++ b/doc/sphinx-guides/source/api/native-api.rst @@ -3936,6 +3936,8 @@ Usage example: curl "https://demo.dataverse.org/api/datasets/previewUrlDatasetVersion/a56444bc-7697-4711-8964-e0577f055fd2?returnOwners=true" +For downloading files using a preview URL token, see the :ref:`Data Access API `. + .. _get-citation: @@ -4002,21 +4004,6 @@ Get Citation by Preview URL Token curl "$SERVER_URL/api/datasets/previewUrlDatasetVersion/$PREVIEW_URL_TOKEN/citation" -.. _get-files-using-preview-url-token: - -Get Files Using a Preview URL Token -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you want to access a dataset's contents shared by a preview URL (see :ref:`previewUrl`, :ref:`get-dataset-by-preview-url-token` and :ref:`create-a-preview-url-for-a-dataset`) using the API, you can use the token in the preview URL as API_TOKEN. - -.. code-block:: bash - - SERVER_URL=https://demo.dataverse.org - PREVIEW_URL_TOKEN=a56444bc-7697-4711-8964-e0577f055fd2 - FILE_ID=1111111 - FILENAME=example.txt - curl -H "X-Dataverse-key:$PREVIEW_URL_TOKEN" -o "$FILENAME" "$SERVER_URL/api/access/datafile/$FILE_ID" - .. _get-dataset-summary-field-names: Get Summary Field Names From 4123645046fcd24a96790fced36f017fcf3c821c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pallinger=20P=C3=A9ter?= Date: Thu, 5 Feb 2026 09:31:36 +0100 Subject: [PATCH 6/6] fix reference in auth.rst --- doc/sphinx-guides/source/api/auth.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/sphinx-guides/source/api/auth.rst b/doc/sphinx-guides/source/api/auth.rst index d470d4a596a..f2f65bc1d15 100644 --- a/doc/sphinx-guides/source/api/auth.rst +++ b/doc/sphinx-guides/source/api/auth.rst @@ -69,7 +69,7 @@ You can reset your API Token from your account page in your Dataverse installati Using Preview URL Tokens as API Token -------------------------------------- -If you want to access a dataset's contents shared by a preview URL (see :ref:`previewUrl`, :ref:`get-files-using-preview-url-token`, :ref:`get-dataset-by-preview-url-token` and :ref:`create-a-preview-url-for-a-dataset`) using the API, you can use the token in the preview URL as API_TOKEN. +If you want to access a dataset's contents shared by a preview URL (see :ref:`previewUrl`, :ref:`get-file-using-preview-url-token`, :ref:`get-dataset-by-preview-url-token` and :ref:`create-a-preview-url-for-a-dataset`) using the API, you can use the token in the preview URL as API_TOKEN. .. code-block:: bash