The token-based authentication is used for access to protected resources and is an alternative to the session-based authentication. The difference here is that for each resource access the token has to be sent along with the request, and that no logout is required.
An authentication token can be obtained either by the user or generated by the administrator.
A token can have an expiration date—this means that a generated token can only be used until a certain date which is given in the user view of the application. If on the other hand the token has no expiration date set, then the token can be used forever. If a token has expired, please generate a new one or contact the administrator to generate one.
The administrator has the possibility to restrict the API access to token-based authentication. In this case only the administrator is able to generate authentication tokens for all users and an API access without a valid authentication token will be denied. If such a case occurs please contact the administrator.
In order to perform privileged operations, authentication may be required. This GET operation performs authentication against the application, returning a authentication token if successful.
Please note that the last generated token for a user is always the only valid one. This means that if one has lost the most recently generated token, then any previous token cannot be used to authenticate and will be treated as an invalid one.
GET /authenticate/getToken
Name | Description |
---|---|
userName | The username to authenticate with |
Type: String | |
Default: None | |
password | The password to authenticate with |
Type: String | |
Default: None |
None
GET /authenticate/getToken?userName=foo&password=bar
HTTP/1.1 200 OK
Content-Type: text/plain
<The authentication token>
HTTP/1.1 401 Unauthorized
Content-Type: text/plain
permission denied
HTTP/1.1 401 Unauthorized
Content-Type: text/plain
user name and password must have a value
HTTP/1.1 401 Unauthorized
Content-Type: text/plain
permission denied
When sending a GET request together with a valid authentication token (which is included in the request header), the user can access the given API resource as authenticated user. This authentication is only valid for the resource requested (resource request without the valid token will be treated as an unauthenticated request). No logout is needed.
GET <resource>
Authorization: Bearer
Name | Description |
---|---|
authToken | The token to authenticate with |
Type: String | |
Default: None |
(according to request)
Authorization: Bearer eyJhbGciOiJIUz...
GET /datastocks
In this example, the data stocks with name "hidden_stock" and "stock_for_authenticated_users" are only visible for the admin user
HTTP/1.1 200 OK
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<sapi:dataStockList xmlns:ni="http://www.ilcd-network.org/ILCD/ServiceAPI/NodeInfo" xmlns:c="http://www.ilcd-network.org/ILCD/ServiceAPI/Contact" xmlns:sapi="http://www.ilcd-network.org/ILCD/ServiceAPI" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.ilcd-network.org/ILCD/ServiceAPI ../schemas/ILCD_Service_API_DataStocks.xsd">
<sapi:dataStock sapi:root="true">
<sapi:uuid>be8d7de2-48d6-46e6-acb4-03952488d524</sapi:uuid>
<sapi:shortName>default</sapi:shortName>
<sapi:name xml:lang="en">Default root data stock</sapi:name>
<sapi:description xml:lang="en">This is the default root data stock</sapi:description>
</sapi:dataStock>
<sapi:dataStock sapi:root="true">
<sapi:uuid>a7459ac9-3497-49f8-9222-dcd1d8887f86</sapi:uuid>
<sapi:shortName>hidden_stock</sapi:shortName>
<sapi:name xml:lang="en"></sapi:name>
<sapi:description xml:lang="en"></sapi:description>
</sapi:dataStock>
<sapi:dataStock sapi:root="false">
<sapi:uuid>d12a770a-72f8-4679-8595-7d97244d602e</sapi:uuid>
<sapi:shortName>stock_for_authenticated_users</sapi:shortName>
<sapi:name xml:lang="en"></sapi:name>
<sapi:description xml:lang="en"></sapi:description>
</sapi:dataStock>
</sapi:dataStockList>
HTTP/1.1 200 OK
Content-Type: application/xml
~~~~ {.myxml} <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <sapi:dataStockList xmlns:ni="http://www.ilcd-network.org/ILCD/ServiceAPI/NodeInfo" xmlns:c="http://www.ilcd-network.org/ILCD/ServiceAPI/Contact" xmlns:sapi="http://www.ilcd-network.org/ILCD/ServiceAPI" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.ilcd-network.org/ILCD/ServiceAPI ../schemas/ILCD_Service_API_DataStocks.xsd"> <sapi:dataStock sapi:root="true"> <sapi:uuid>be8d7de2-48d6-46e6-acb4-03952488d524</sapi:uuid> <sapi:shortName>default</sapi:shortName> <sapi:name xml:lang="en">Default root data stock</sapi:name> <sapi:description xml:lang="en">This is the default root data stock</sapi:description> </sapi:dataStock> </sapi:dataStockList> ~~~
HTTP/1.1 403 Forbidden
Content-Type: text/plain
Permission denied.
HTTP/1.1 500 Internal Server Error
Content-Type: application/xml
An exception will be shown saying that an authentication error occurred.