Session

The REST API of webPDF is a "stateful API", i.e. with the creation of an access token in the context of authorization and authentication a session is created. The session is associated with the access token and exists as long as the token is valid (timeout) or the token is actively invalidated by a logout.

The session contains the "document storage" (storage) on the server to store the documents to be processed between each web service call.

Expiration time (timeout)

In the REST API, each granted access token is assigned a session that has a specific expiration time (timeout) based on the access token. The session expiration time is supplied as an "expiresIn" in the response structure to an "authentication/user/login".

curl -X POST -i -H 'Accept: application/json' -H 'Authorization: Basic YWRtaW46YWRtaW4=' http://localhost:8080/webPDF/rest/authentication/user/login  
HTTP/1.1 200  
  
Cache-Control: no-cache, no-store, no-transform, proxy-revalidate, max-age=0  
Content-Type: application/json  
Content-Length: 44  
  
{  
  "expiresIn": 3599,   
  "token": "eyJraWQiOiJyb3ZZTFQ4TXgwcTd1WW1i ... CO2TLHCiQCsuMf-1Vw",  
  "refreshToken": ""  
}

It is specified in seconds at the time the access token is issued, i.e. in the above example the session will expire in 3599 seconds.

End session with logout

If a session is terminated (logout) or expires (timeout), the access token becomes invalid, the storage is removed, and all documents in it on the server are deleted.

curl -X GET -i -H 'Accept: application/json' -H 'Authorization: Bearer eyJraWQiOiJyb3ZZTFQ4TXgwcTd1WW1i ... CO2TLHCiQCsuMf-1Vw' http://localhost:8080/webPDF/rest/authentication/user/logout

caution

You should always call a logout after a login, and after all operations performed, to end the session and thus avoid unnecessary memory consumption.

Extend session

To prevent a session from expiring, the access token must be renewed before the session expires. This requires another token, the refresh token. By using the refresh token, the session is extended and a new access token with a new expiration time (timeout) and a new refresh token are created. From this point on, only the newly created tokens may be used, e.g. to authorize web service calls or to perform a new session extension.

To receive a refresh token, it must be actively requested during authentication.

caution

Refresh tokens can only be used if they are issued by the local authorization of the webPDF server. Refresh tokens that originate from an OAuth2 provider, for example, cannot be used. In this case, call the corresponding interface of the OAuth2 provider to obtain a new access token. Use this new token in the webPDF Web Services authorization, which then automatically renews the session when the new token is used.