Share:
ClickHelp Documentation

The Token Login Mechanism

ClickHelp provides a flexible way to control who can access the content in your portal. You can create a public document, a private publication available only to authenticated users, or a restricted publication that can be accessible by users of a particular type - Power Readers. You can create Power Readers manually or use ClickHelp REST API, so your end-users get credentials for your ClickHelp portal to access documentation.

However, often, you don't want to bother your users with an additional set of credentials just to let them access documentation. At the same time, you may want non-legitimate users to be forbidden from accessing the content. So you need to have a way to authenticate users of your application or service in your ClickHelp portal without making them deal with the portal's login process. The most secure way to do this is to use the SSO technology, and specifically the OpenID Connect mechanism to authenticate users by your service native accounts. It can be impossible in some situations, or you may not have the SSO implementation on your end. For example, if you are working with a desktop application that does not require users to log in, and you don't have an authentication endpoint on the Internet, the SSO approach cannot be used.

In such cases, it is possible to use another approach - login tokens. Your application can generate a one-off login token for a generic Power Reader user by calling the corresponding API method and then provide links to the documentation with this token included in the URL. Here is an example of how a topic link with authentication token may will look like: https://myportal.clickhelp.co/articles/my-publication/my-topic?t=<TOKEN>.

Besides direct links to topics, you can use the "t=<TOKEN>" parameter with smart links and links to publications.

When someone opens this link, ClickHelp identifies the related Power Reader user and silently authenticates the user in the current browser. Until the authentication cookie is expired (by default, in 48 hours), the user has access to the documentation without a need for a new login token.

Note that a login token cannot be used more than once. However, if a user is already authenticated, you can add an expired or used token to a topic link, and this won't produce any errors. If a new unexpired token is used and a user is authenticated already, the token is ignored and not disposed. The recommended approach is to generate a new token every time you need to provide a user with a link. You also can get a token when your application is launched, and use this token in all links. In this case, it could be a good idea to specify a more extended expiration period for the token, because the default 30 minutes can be not enough for the end-user to open the first link to the documentation.