KnowledgeSmart API logic Visio flow diagram

Quick Answer

An external system signs a user in to KnowledgeSmart without a password by requesting a login token with GET /Users/RequestLoginToken and sending the user to the KnowledgeSmart /trafficcop.aspx page with the user's UserID, the login token and a Destination value, within 10 minutes of requesting the token.

What This Article Helps With

This article explains how to use KnowledgeSmart login tokens to sign a user in to the KnowledgeSmart admin site or user pages from another system and send the user straight to a specific page, such as an assessment to take or a test report. It is intended for developers building the sign-in and for the teams supporting it.

Before You Start

KnowledgeSmart API key: the basic API key for the KnowledgeSmart account, used to call the KnowledgeSmart API at https://online.knowledgesmart.net/api.
Secret key: an additional secret key shared between KnowledgeSmart and your organization through a business process. The secret key is separate from the KnowledgeSmart API key.
A user in the same KnowledgeSmart account: KnowledgeSmart issues a login token only for a user who belongs to the KnowledgeSmart account that the API key belongs to.

How to Sign a User In with a KnowledgeSmart Login Token

Authenticate to the KnowledgeSmart API with the KnowledgeSmart API key.
Get the user's KnowledgeSmart UserID with GET /Users/GetUserFromEmail. To look up many users, iterate the results of GET /Users/GetAllUsers instead.
Request a login token with GET /Users/RequestLoginToken, passing the UserID and the secret key.
Build a URL to the KnowledgeSmart /trafficcop.aspx page with a querystring containing the UserID, the login token and a Destination value.
Add the extra querystring parameter that the Destination value requires, if any.
Send the user to the URL.
Confirm that the user is signed in to KnowledgeSmart and lands on the page for the Destination value.

Destination Values for the KnowledgeSmart Login URL

The Destination value controls which KnowledgeSmart page the user lands on. Every Destination value requires the userid and logintoken querystring parameters.

auto: an admin user's default landing page, based on their admin type.
userlist: the user list page, for an admin user.
userhome: the home page in the user area, for a non-admin user.
userarea: the assessments page in the user area, for a non-admin user.
taketest: an assessment for the user to take. Also requires inviteID, which can be retrieved from another KnowledgeSmart API endpoint, for example GET /Assessments/GetAllAssignedAssessments.
testreport: a test report. Also requires resultID.
examcertificate: an exam certificate. Also requires resultID.

Supported Login Destinations

The Destination parameter determines where users are redirected following successful authentication. All destinations require a valid userid and logintoken. Some destinations require additional parameters, as indicated below.

Table of Destination values for the KnowledgeSmart login URL, showing the querystring parameters each Destination value requires

What Happens When the User Opens the Login URL

The KnowledgeSmart /trafficcop.aspx page checks that the login token and UserID combination is correct and that the login token has not expired. A KnowledgeSmart login token expires 10 minutes after it is requested.

If both checks pass: KnowledgeSmart signs the user in and opens the page for the Destination value. If no Destination value is included, KnowledgeSmart opens the dashboard home page.
If either check fails: KnowledgeSmart does not sign the user in and opens an error or information page instead.

KnowledgeSmart adds an audit record for every sign-in attempt, whether the attempt succeeds or fails.

Helpful Tips

We recommend requesting the login token at the moment the user needs to sign in, rather than generating links in advance, because the login token expires shortly after it is requested.
Keep the secret key on the server side. The secret key is used only in the call to RequestLoginToken and never belongs in the URL sent to the user.

Common Questions

Why did the user land on an error page instead of being signed in?

KnowledgeSmart opens an error or information page when the login token and UserID combination is incorrect or the login token has expired. Request a new login token with GET /Users/RequestLoginToken and send the user a new URL.