Authentication : Token-Based

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.

Obtain Token

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.

Requests

Syntax

GET /authenticate/getToken

Request Parameters

Name Description
userName The username to authenticate with
Type: String
Default: None
password The password to authenticate with
Type: String
Default: None

Responses

Response Elements

None

Examples

Sample Request

GET /authenticate/getToken?userName=foo&password=bar

Sample Response if Login Successful

HTTP/1.1 200 OK
Content-Type: text/plain

<The authentication token>

Sample Response if Wrong User Name or Password

HTTP/1.1 401 Unauthorized
Content-Type: text/plain

permission denied

Sample Response if User Name or Password Missing in Request

HTTP/1.1 401 Unauthorized
Content-Type: text/plain

user name and password must have a value

Sample Response if User Not Allowed to Use/Generate Token

HTTP/1.1 401 Unauthorized
Content-Type: text/plain

permission denied

API Access With Authentication Token

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.

Requests

Syntax

GET <resource>

Request Headers

Authorization: Bearer

Name Description
authToken The token to authenticate with
Type: String
Default: None

Responses

(according to request)

Examples

Sample Request

Authorization: Bearer eyJhbGciOiJIUz...
GET /datastocks

Sample Response if Generated Token Valid

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>

Sample Response if Generated Token Not Valid And API Access Not Restricted to Authenticated Users

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> ~~~

Sample Response if Generated Token Not Valid And API Access Restricted to Authenticated Users

HTTP/1.1 403 Forbidden
Content-Type: text/plain

Permission denied.

Sample Response if Generated Token Expired

HTTP/1.1 500 Internal Server Error
Content-Type: application/xml

An exception will be shown saying that an authentication error occurred.