This article discusses functionality that is included in the Aha! Knowledge Advanced plan. Please contact us if you would like a live demo or want to try using it in your account.

Aha! Knowledge | JSON Web Token

JSON web token (JWT) is a technique that can be used for single sign-on (SSO) between a custom application and another application. In this case, JWT can be used for SSO to an Aha! Roadmaps knowledge base so that users of your web application can log in to the knowledge base and access documentation using their application credentials.

Click any of the following links to skip ahead:

The JWT single sign-on experience

When a user authenticates using SSO, they go through the following process:

  1. The user navigates to your knowledge base e.g. https://myaccount.aha.site/kb/kbname.

  2. Your knowledge base recognizes that your account is configured to use JWT.

  3. The user's browser is redirected to your application using the Remote login URL that you configured on the JSON Web Token (JWT) configuration screen.

  4. Your application recognizes that it has received a JWT authentication request.

  5. Your application authenticates the user.

  6. Your application builds a JWT response and redirects the user back to knowledge base using the URL https://myaccount.aha.site/auth/jwt/callback, including the JWT response.

  7. Your knowledge base validates the JWT response.

  8. The user is granted access to the knowledge base.

All of the communication between your knowledge base and your application happens via URL parameters in the user's browser. There is no direct communication between the systems.



You can configure SSO differently for each knowledge base in your Aha! account. To get started, go to Settings ⚙️ Account Knowledge Knowledge bases. You will need to be an administrator with customizations permissions to configure a knowledge base.

To enable JSON Web Token SSO in your knowledge base:

  1. Navigate to Settings ⚙️ Account Knowledge Knowledge bases.

  2. Click the knowledge base you want to configure. This opens that knowledge base's settings.

  3. On the Overview tab, find the Authentication settings. Next to the Authentication dropdown, select SSO.

  4. In the SSO identity provider dropdown, select +Add new provider.

  5. On the next screen, enter a Name to identify the SSO configuration. Next to Type, select JSON Web Token and click Save.

    If you already have SSO set up for a separate knowledge base and would like to share that SSO configuration with this one, you can select the existing provider you have already set up during this step and skip adding a new one.

  6. The JSON Web Token configuration will display. Fill in the remaining fields.

  7. Click Enable SSO to enable the configuration.

If the same identity provider configuration is used for more than one knowledge base, then a user may be prompted to choose which knowledge base they are logging in to. If the identity provider supports relay state, or state passthrough, then service provider-initiated logins (when the login starts at your Aha! account) will redirect the user to the correct knowledge base immediately.


Building the JWT response

When it receives a JWT authentication request, your application must generate a JWT response. The response should include a HS256-signed token containing these fields:

  • iat: The integer time the response was created in seconds since the Unix epoch.

  • jti: A randomly created token that uniquely identifies this response.

  • first_name: The first name of the user that was authenticated.

  • last_name: The last name of the user that was authenticated.

  • email: The email address of the user that was authenticated.

The name and email fields are not used by the knowledge base, so any values can be used in these fields.

Here is sample Ruby code to generate the JWT payload which is signed and base 64 encoded:

iat = Time.now.utc.to_i
jti = "#{iat}/#{rand(36**64).to_s(36)}"
payload = JWT.encode(
    iat: iat,
    jti: jti,
    first_name: "John",
    last_name: "Doe",
    email: "john.doe@aha.io",

An example JWT input looks like this. Note that the iat is a number and the other fields are strings:

{ "iat": 158258345634, "jti": "1234567890abcdefg", "first_name": "John", "last_name": "Doe", "email": "john.doe@aha.io" }

The URL the user should be redirected back to for login will look like this:


If the request contains state query parameter then the value of that parameter should also be included in the redirect. The state query parameter ensures the user is redirected back to the correct knowledge base.


Single sign-out

Single sign-out allows the user to sign out of one application and be automatically signed out of both applications. Single sign-out is optional.

There are two parts of single sign-out:

  1. Sign out from the knowledge base. Enter a Remote logout URL in the JWT configuration. When the user logs out of the knowledge base they will be redirected to this URL. Your application should detect the access of this URL and also log the user out of the application.

  2. Sign out from your application. When the user logs out of your application you should redirect them to the /portal_session/logout URL of the knowledge base. If you are sharing your SSO configuration with another knowledge base, this will log the user out of that knowledge base as well. The user will be redirected back to your application to log in again.

For those who prefer a SAML single sign-on process, your Aha! account also provides this capability.



We have created an article to help you troubleshoot common SSO configuration issues, complete with explanations and resolutions.

The best place to start in most of these situations is the Recent SSO events for your SSO configuration, at the bottom of the configuration page. Those messages will help diagnose and solve the problem.


If you get stuck, please reach out to our Customer Success team. Our team is made up entirely of product experts and responds fast.

Suite overview
Aha! Roadmaps
Aha! Ideas