Summary

• Page properties (2 modified, 0 added, 0 removed)

Details

Page properties

Author

...	...	@@ -1,1 +1,1 @@
1		-XWiki.mmorgan
	1	+XWiki.eapapp

Content

...	...	@@ -1,57 +1,35 @@
1		-== Introduction ==
	1	+== Access to datasets shared via the Human Data Gateway ==
2	2
3		-This page describes how to access data via the Human Data Gateway (HDG). The HDG service was installed to control access to sensitive human data which is shared in strongly pseudonymized form.
	3	+You can now browse KnowledgeGraph datasets through the data proxy as an authenticated user via the datasets API: [[https:~~/~~/data-proxy.ebrains.eu/api/docs#/datasets>>https://data-proxy.ebrains.eu/api/docs#/datasets]]
4	4
5		-=== What datasets are available? ===
	5	+To get access to datasets protected by the HDG, use the {{code}}datasets/{dataset_id}{{/code}} endpoint.
6	6
7		-Datasets that are released in Knowledge Graph v2 or v3 are available. The [[KG's controlled access filter>>https://search.kg.ebrains.eu/?facet_type[0]=Dataset&facet_Dataset_dataAccessibility[0]=Controlled%20access]] can be used to list datasets accessed via the HDG.
	7	+1. First perform a {{code}}POST /datasets/{dataset_id}{{/code}} request to start the HDG flow.
	8	+1. An e-mail is then sent to the user with the terms of use to validate the access.
	9	+1. Once the access has been validated, the user is redirected by default to the KnowledgeGraph page of the dataset. This redirection can be customized for third-party integration.
8	8
9		-== Access via the UI ==
	11	+**Note:** For publicly available datasets, (% id="cke_bm_564S" style="display:none" %) (%%)the {{code}}datasets/{dataset_id}{{/code}} endpoint can be used via GET, without the extra validation round.
10	10
11		-(% class="wikigeneratedid" %)
12		-In order to access those datasets, the following steps are involved:
	13	+== Example of programmatic integration for a third party ==
13	13
14		-1. A user finds a dataset in the Knowledge Graph and logs in to the KG (or vice versa)
15		-1. The user requests access to the dataset from the Get Data section of the dataset card.
16		-1. The HDG service verifies that the user is authenticated.
17		-1. An e-mail is then sent to the user with the [[Data Use Agreement>>https://ebrains.eu/terms/#data-use-agreement]] and a link.
18		-1. By clicking the link in the e-mail, the user accepts the terms and proves s/he has access to the e-mail. The same link can be used multiple times within a predefined period (currently 24 hours).
19		-1. Clicking the link directs the user to the HDG service which:
20		-11. verifies that the user is authenticated, and
21		-11. logs the consent to the DUA and the access to the data.
22		-11. redirects the user to a data-proxy UI interface providing access to the objects in the dataset
23		-1. The user can browse the dataset contents.
24		-
25		-== Programmatic access ==
26		-
27		-Programmatic access to the HDG service was mainly designed to allow other services to consume controlled data on behalf of the end-user. For example, a user can browse a controlled brain scan. The image viewer will then programmatically access the HDG controlled data and the end-user will validate the access in her/his e-mail.
28		-
29		-=== Access to datasets shared via the Human Data Gateway ===
30		-
31		-You can now browse Knowledge Graph datasets through the data proxy as an authenticated user via the datasets API: [[https:~~/~~/data-proxy.ebrains.eu/api/docs#/datasets>>https://data-proxy.ebrains.eu/api/docs#/datasets]]
32		-
33		-To get access to datasets protected by the HDG, use the (% style="background-color:lightgray" %)datasets/{dataset_id}(%%) endpoint.
34		-
35		-1. First perform a (% style="background-color:lightgray" %)POST /datasets/{dataset_id}(%%) request to start the HDG flow.
36		-1. An e-mail is then sent to the user with the Data Use Agreement and a link. By clicking the link, users accept the DUA and prove they have access to the e-mail.
37		-1. Once the access has been validated, the user is redirected by default to the Knowledge Graph page of the dataset. This redirection can be customized for third-party integration.
38		-
39		-**Note:** For publicly available datasets, the (% style="background-color:lightgray" %)datasets/{dataset_id}(%%) endpoint can be used via GET, without the extra validation round.
40		-
41		-=== Example of programmatic integration for a third party ===
42		-
43	43	1. A user wants to access a KG dataset in your third-party application.
44		-1. The third-party application calls (% style="background-color:lightgray" %)GET /datasets/{dataset_id}(%%) with the user token in order to get information about the dataset or download it.
	16	+1. The third-party application calls {{code}}GET /datasets/{dataset_id}{{/code}} with the user token in order to get information about the dataset or download it.
45	45	(% start="1" style="list-style-type:upper-alpha" %)
46	46	11. The dataset is not protected ~-~-> A successful response is sent.
47		-11. The dataset is protected ~-~-> An HTTP 401 response is sent back. In the 401 JSON response, a (% style="background-color:lightgray" %)can_request_access(%%) field is specified. If true, it means that it is possible to request access to that dataset using (% style="background-color:lightgray" %)POST /datasets/{dataset_id}(%%).
48		-1. The third-party application asks the user if they want to request access, and if so then sends (% style="background-color:lightgray" %)POST /datasets/{dataset_id}?redirect_uri=https:~/~/mythirdpartyapp.eu/{dataset_id}(%%).
	19	+11. The dataset is protected ~-~-> A 401 response is sent back. In the 401 json response, a {{code}}can_request_access{{/code}} field is specified. If true, it means that it is possible to request access to that dataset using {{code}}POST /datasets/{dataset_id}{{/code}}.
	20	+1. The third-party application asks the user if they want to request access, and then sends {{code}}POST /datasets/{dataset_id}?redirect_uri=https://mythirdpartyapp.eu/{dataset_id}{{/code}}.
49	49	1. If the request is successful, an e-mail is sent to the user.
50		-1. Once the user has clicked on the e-mail link, access is granted and the user is redirected to (% style="background-color:lightgray" %)https:~/~/mythirdpartyapp.eu/{dataset_id}(%%).
51		-1. (% style="background-color:lightgray" %)GET /datasets/{dataset_id}(%%) now answers with successful responses.
	22	+1. Once the user has clicked on the e-mail link, access is granted and the user is redirected to {{code}}https://mythirdpartyapp.eu/{dataset_id}{{/code}}.
	23	+1. {{code}}GET /datasets/{dataset_id}{{/code}} now answers with successful responses.
52	52
53		-=== Front-end implementation ===
54	54
55		-The UI access described above implements this flow and is available at (% style="background-color:lightgray" %)https:~/~/data-proxy.ebrains.eu/datasets/{dataset_id}(%%).
	26	+== Front-end implementation ==
56	56
	28	+An actual implementation of this flow is available at {{code}}data-proxy.ebrains.eu/datasets/{dataset_id}{{/code}}.
	29	+
	30	+
	31	+== What datasets are available? ==
	32	+
	33	+Datasets that are released in KnowledgeGraph v2 or v3 are available.
	34	+
57	57