The Token Login Mechanism
Login Tokens allow you to automatically authenticate your users as Power Readers in your ClickHelp portal upon clicking a link in your application or website.
If you don't want your readers to deal with the login process through a set of credentials, the Login Tokens come in handy. They are helpful if implementing the recommended Single Sign-On (SSO) feature is not an option, but it is necessary to bypass the ClickHelp login screen and seamlessly authenticate users of a third-party application or website in ClickHelp.
Login Token
A token is a unique string that can be specified as a URL parameter to make such a link log users in under a specific Power Reader account. You can generate a token for a Power Reader account by calling the following API method: [API] Get Login Token.
In the API response, you will get only the login token, not the full URL. You will need to append the token to a link. Read Use Login Token to understand the whole process.
When such a link is used, your ClickHelp portal will validate the token and automatically authenticate the reader. This way, you can give a link to a password-protected publication that includes a login token. This will allow the reader to access this topic without entering a password.
| A login token does not define which restricted publications a reader can access and serves only as a means to authenticate users under a particular account. The access is determined by specific publication or Power Reader account setup: Restricted User Manuals. |
Login tokens are disposable; by default, every token can be used only once. Optionally, it is possible to create multi-use tokens that can be used multiple times. Also, for security reasons, every token has an expiry date set through a token creation API method parameter. This means that your application may need to generate new login tokens for documentation links occasionally.
Supported Link Types
These are the types of links that support tokens in ClickHelp:
- Direct links to topics.
- Smart links.
- Links to publications.
-
Links with a hashbang.
When using links with hashbangs, the token parameter must be inserted before the hashbang, like this: /articles/?t=eyJ0eXAiOiJKV1QiLC#!my-publication/my-topic
Links to public pages
It's important to append tokens to links leading to restricted publications. If you append it to a link to a public page, such as the Home page, ClickHelp will ignore the token since it's not necessary to authenticate users in this case to show them the page.
What you can do is route users to the login page with the ReturnUrl parameter, authenticating and then automatically redirecting them to the URL you specify in the parameter:
https://hedronlabs.clickhelp.co/login/?ReturnUrl=%2Fhome%2F?t=SMxf5RlJ586y4iYWemQyECH51ueoOdBF
Token Expiration
Login tokens become invalid in two cases:
- When its expiration date is due.
- Right after a one-time token is used for authentication.
By default, login tokens are created as one-time tokens with a 30-minute expiration period. You can control whether a login token can be used only once or multiple times and set its expiration date by specifying the corresponding API query parameters when making the Get Login Token API call.
If a user is already authenticated in a web browser session, adding an expired or used one-time token to a topic link won't produce any errors - the token will be ignored.
If a valid, unexpired one-time token is used, and a user is already authenticated, the token is ignored and not disposed of. The recommended approach is to generate a new token whenever you need to provide a user with a link. You can also 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 may not be enough for the end-user to open the first link to the documentation.
To learn more about token expiration, read the following topic: Session Control and Expiration.