On this page


Teamwork Cloud REST API has an endpoint, which implements token-based authentication described in the Token-based authentication page.

Setting up token-based authentication

To set up Teamwork Cloud and Authentication server for token-based authentication using REST API endpoint

  1. Set up Authentication server to work with your SAML/SSO, if needed.
  2. Open <install_root>/WebAppPlatform/shared/conf/authserver.properties.

  3. Find key authentication.client.ids and add ,twc-rest-api at the end of the value. Save and close the file.

    The comma before twc-rest-api is a separator.

  4. Open <install_root>/TeamworkCloud/configuration/application.conf.
  5. Find the esi.auth block and set the server value to your authentication server IP. Save and close the file.
  6. Restart the Authentication server and Teamwork Cloud server.

Using token-based authentication

To use token-based authentication

  1. Open REST API at the following URL: https://<ip>:8111/osmc/authen/login on a browser.
  2. You should be redirected to the Authentication server login page.
  3. Enter your credentials. The browser shows you a token, usually starting with eyJ….



  4. Copy the token and use it to log on to REST API.

    The token is used in an Authorization header with the Token Type.

For example (using a token with cURL):

curl -v -k -H "Authorization: Token
eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJBZG1pbmlzdHJhdG9yIiwiYXVkIjoidHdjLXJlc3QtYXBp
IiwiaXNzIjoiaHR0cHM6XC9cLzEyNy4wLjAuMTo4NTU1XC9hdXRoZW50aWNhdGlvbiIsImV4cCI6M
TYwNjI5OTc3NywiaWF0IjoxNjA2Mjk4ODc3fQ.bA-
S5hHeSlV8AFoQVzzfIseC3qlmqQoBQREiapHN6I5CcvwetKdSVztWKkssSGjm31Y1zqoULio7_1Ma
mtGBbbzvA1WWQYFRiYk0D612yNDv4uNHBbNLNEv61TYNLwdPwPh0atVRehkh-
LSgjipXTvXj4mZViE0NHKIG9U7htA9Zzvxvck2JDXe_eU2-
4TCNm8II89ROaEb1tZ5nD84ieRbzJWqrcVTdqU2YfbIUeew5Nir8obkLYgixBXFKWsTHi3jNuoBx3
KcAIyZqL6cjtsCER4wbk4PEEDC57UVsOcsXWr6yvXIoVdJMOiDHo_fJMkgOjDqSyIL-2B21O-Y-GA"
https://127.0.0.1:8111/osmc/login

The result is as follows:

> GET /osmc/login HTTP/1.1
> Host: 127.0.0.1:8111
> User-Agent: curl/7.55.1
> Accept: */*
> Authorization: Token
eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJBZG1pbmlzdHJhdG9yIiwiYXVkIjoidHdjLXJlc3QtYXBp
IiwiaXNzIjoiaHR0cHM6XC9cLzEyNy4wLjAuMTo4NTU1XC9hdXRoZW50aWNhdGlvbiIsImV4cCI6M
TYwNjI5OTc3NywiaWF0IjoxNjA2Mjk4ODc3fQ.bA-
S5hHeSlV8AFoQVzzfIseC3qlmqQoBQREiapHN6I5CcvwetKdSVztWKkssSGjm31Y1zqoULio7_1Ma
mtGBbbzvA1WWQYFRiYk0D612yNDv4uNHBbNLNEv61TYNLwdPwPh0atVRehkh-
LSgjipXTvXj4mZViE0NHKIG9U7htA9Zzvxvck2JDXe_eU2-
4TCNm8II89ROaEb1tZ5nD84ieRbzJWqrcVTdqU2YfbIUeew5Nir8obkLYgixBXFKWsTHi3jNuoBx3
KcAIyZqL6cjtsCER4wbk4PEEDC57UVsOcsXWr6yvXIoVdJMOiDHo_fJMkgOjDqSyIL-2B21O-Y-GA
>
< HTTP/1.1 204 No Content
< Content-Length: 0
< Content-Type: application/octet-stream
< Date: Wed, 25 Nov 2020 10:08:44 GMT
< Accept-Ranges: bytes
< Server: Restlet-Framework/2.2.3
< Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept
< Set-Cookie: twc-rest-current-user=Administrator; Path=/osmc; Expires=Wed, 25 Nov 2020 10:23:44 GMT
< Set-Cookie: twc-rest-session-id=f40ef933-5461-4058-a1e7-9b8d4021aa8a; Path=/osmc; Expires=Wed, 25 Nov 2020 10:23:44 GMT
<
* Connection #0 to host 127.0.0.1 left intact

Limitations

This REST API endpoint only displays the ID token. Usually, ID token is not very long-living. You can configure the ID token expiration in authserver.properties file (using property authentication.token.expirity).

Usually the ID token needs to be refreshed as described in the page Token-based authentication. However, this REST API does not display a refresh token, which is needed to refresh the ID token.

As a workaround, long-living ID tokens can be generated by adding ,twc-rest-api to the authserver.properties file property authentication.client.unlimited. In such case, ID token expiration will be calculated using property authentication.unlimited.token.expirity.

Use this feature with caution and make sure that such long-living ID token is adequately protected.