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 using tokens to reuse the old session. The process to do so is described below.
In general, there are two options: either using cookies to keep the session alive or using tokens to reuse the old session. The process to do so is described below.
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 the/Account/Login 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, a 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 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 lifetime 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 the post method. This call requires a body in which the target product, the usage (Multi, Single), and the lifetime are specified. Please have a look at the following example JSON body to create a token:
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, a 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 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 lifetime 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 the post method. This call requires a body in which the target product, the usage (Multi, Single), and the lifetime 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"
}
"TargetProducts":["PlatformService"],
"Usage":"Multi",
"Lifetime":"1.00:00:00"
}
The response will contain the token, that is provided by the platform. Afterward, the authentication can be performed by sending the token via post to /Account/TokenLogOn. This authentication method allows the reuse of the user license, which was in use before the log-off operation. The token has a lifetime, which can be set when requesting the token (Lifetime parameter). Most of the DocuWare applications (e.g., Desktop Apps) use a token with a lifetime of 365 days. To repeat this process, it is important to create a new token before logging off and always use the latest token to perform the login operation.
KBA is applicable to both Cloud and On-premise Organizations.
