How to use authentication¶
As described in section Authentication, there are two methods to access protected data in the dataset: Basic and OAuth2 authentication. Both authentication methods can be used within a browser or from the command line, with only slight differences. In this section we show how to use authentication within the Open Data Hub, provided that you owe an username and a password to access the closed data in the datasets.
To obtain the credentials, please address your enquiry to the contact email of the dataset you would like to access.
Basic authentication¶
Basic authentication can be used with the Datasets in the Tourism Domain.
If you use a browser.
Go to the swagger interface of the API (in our example we use the accommodation dataset). Here, authentication can be used simply by trying to execute an API call. As Figure 2 shows, click on the button and a new dialog will appear, in which you can supply the username and password. This method is convenient if you need to call one method at a time.
However, if you need to execute multiple API call on the same dataset, a more useful method is to insert the username and password directly in the two appropriate fields on top of swagger interface (they are framed in red in Figure 3).
If you use the Command Line Interface.
Open a shell on your workstation and use a tool like curl or wget, with the appropriate options:
-
-X
¶
Specify the request method (GET)
-
--header
,
-H
¶
Add extra header information to be included in the request.
Note that the --header
option is used twice: The first to
receive the answer in text/html format, the second to
provide the credentials required to access protected content.
curl -X GET --header 'Accept: text/html' --header 'Authorization: Basic dGVzdDp0ZXN0aGFsbG8=' 'http://tourism.opendatahub.bz.it/Accommodation'
OAuth2 authentication¶
OAuth2 authentication can be used in all the Datasets in the Mobility Domain
that are marked with the badge, so pick one dataset and go to
its swagger interface, whose URL is provided together with the
information of the dataset.
Note
As of Feb 06, 2019, authentication is not yet publicly available, so the following guidelines can not yet be put in practice.
If you use a browser
Make sure you have obtained a valid username and password, then open the /rest/refresh-token method and write you username and password in the two user and pw fields, respectively, as shown in Figure 4.
If your credentials are valid, you will receive a new token, otherwise the response will be a 401 Unauthorized error message.
The token you received can be used in any of the API’s methods that
require authorisation. A sample call is shown in figure
Figure 5. Note the syntax of the Autorization
parameter: You must use prefix the authentication token with the
Bearer string, followed by an empty space, then by the
token.
In case you do not respect the Authorization+space+token sequence, use additional separators in the sequence (like Figure 6 shows), or use an invalid token, you will receive an 401 - Unauthorized HTTP response.
If you use the Command Line Interface.
Like in the case of basic authentication, API calls can be done using
a tool like curl or wget, with the same
-X
and --header
options, with the slight
difference that the --header
option is used twice: The first
to require the format of the response, the second to provide the
credentials.
curl -X GET "http://bdp-test-env.b7twwguhyj.example.com/emobility/rest/get-records?station=83&name=CP1-Tignale&seconds=50" --header "Accept: */*" --header 'Authorization: Bearer <token>'
Make sure to replace the <token> with the actual token you received.