Question:
How can 401 errors in regards to no free licenses be avoided, when using the DocuWare API?
Answer:
In general there are two options. Either using cookies to keep the session alive, or the usage of tokens to reuse the old session. The process to do so is described in the following.
In general there are two options. Either using cookies to keep the session alive, or the usage of tokens to reuse the old session. The process to do so is described in the following.
Authentication:
Before the cookie/token can be used an initial session is required. Therefore the application has to log in to DocuWare. To do so send a post request, containing the authentication data to /Account/Logon endpoint. The response will at least contain the following two cookies: .DWPLATFORMAUTH and DWPLATFORMBROWSERID.
LogOff:
When a log off is performed via the /Account/LogOff endpoint, the user will be logged out of DocuWare. The current session cookie will become invalid and cannot be used afterwards. This means, that a new session has to be created. If there is another login attempt within two minutes and no free license is available, 401 HTTP status code with the message "None of the registered licenses are available for client [user name]" will be returned.
Avoid the 401 response:
Either one of the following to options can be used to avoid the 401 status code, described above.
Keep the session alive using cookies:
After logon store the .DWPLATFORMAUTH cookie in a cookie container. Now the cookie from the cookie container can be used in every following request to the DocuWare API. As long as now log off is performed, the application can use the old session without having to re-authenticate and will only use one client license. Use this method, if the application sends requests to the DocuWare API in an irregular time frame. The life time of the cookie is set to 20 years and should work as long as no log off is performed.
Reconnect within two minutes using a token:
Sometimes a reconnect to the DocuWare API within two minutes after calling the /Account/LogOff endpoint is necessary. To avoid the 401 error, a token can be used, instead of keeping the session alive using the cookie. The token can be created before the log off by calling the /Organizations/LoginToken endpoint via post method. This call requires a body, in which the target product, the usage (Multi, Single) and the life time are specified. Please have a look at the following example JSON body to create a token:
{
"TargetProducts":["PlatformService"],
"Usage":"Multi",
"Lifetime":"1.00:00:00"
}
The response will contain the token, that is provided by the platform. Afterwards the authentication can be performed by sending the token via post to /Account/TokenLogOn. This authentication method allows to reuse the user license, which was in use before the log off operation. The token has a life time, which can be set, when requesting the token (Lifetime parameter). Most of the DocuWare applications (e.g. Desktop Apps) use a token with lifetime of 365 days. To repeat this process it is important to create a new token before log off and always use the latest token to perform the login operation.
LogOff:
When a log off is performed via the /Account/LogOff endpoint, the user will be logged out of DocuWare. The current session cookie will become invalid and cannot be used afterwards. This means, that a new session has to be created. If there is another login attempt within two minutes and no free license is available, 401 HTTP status code with the message "None of the registered licenses are available for client [user name]" will be returned.
Avoid the 401 response:
Either one of the following to options can be used to avoid the 401 status code, described above.
Keep the session alive using cookies:
After logon store the .DWPLATFORMAUTH cookie in a cookie container. Now the cookie from the cookie container can be used in every following request to the DocuWare API. As long as now log off is performed, the application can use the old session without having to re-authenticate and will only use one client license. Use this method, if the application sends requests to the DocuWare API in an irregular time frame. The life time of the cookie is set to 20 years and should work as long as no log off is performed.
Reconnect within two minutes using a token:
Sometimes a reconnect to the DocuWare API within two minutes after calling the /Account/LogOff endpoint is necessary. To avoid the 401 error, a token can be used, instead of keeping the session alive using the cookie. The token can be created before the log off by calling the /Organizations/LoginToken endpoint via post method. This call requires a body, in which the target product, the usage (Multi, Single) and the life time are specified. Please have a look at the following example JSON body to create a token:
{
"TargetProducts":["PlatformService"],
"Usage":"Multi",
"Lifetime":"1.00:00:00"
}
The response will contain the token, that is provided by the platform. Afterwards the authentication can be performed by sending the token via post to /Account/TokenLogOn. This authentication method allows to reuse the user license, which was in use before the log off operation. The token has a life time, which can be set, when requesting the token (Lifetime parameter). Most of the DocuWare applications (e.g. Desktop Apps) use a token with lifetime of 365 days. To repeat this process it is important to create a new token before log off and always use the latest token to perform the login operation.