JWT

JSON Web Token (JWT) is an encrypted token format that securely transfers authentication and authorization data between two applications. In Document360, JWT is used to authenticate reader logins to your knowledge base site.

Document360 uses an approach similar to PKCE (Proof Key for Code Exchange, a secure OAuth method) to generate the JWT token.

Flowchart illustrating user login process for accessing knowledge base content securely.

When NOT to use JWT

JWT is not the right choice if:

Your organization already uses a centralized Identity Provider (Okta, Microsoft Entra, Google Workspace) and wants readers to authenticate through it. Use SAML or OpenID Connect instead. To do so, read Single Sign-On (SSO).
You need features such as auto-register SSO readers, reader self-registration, or skipping Document360's common sign-in page. These features are not supported with JWT.
You need user (portal) authentication. JWT only supports reader authentication to the knowledge base site.

JWT vs SAML vs OpenID Connect

Feature	JWT	SAML / OpenID Connect
Reader management	Readers are authenticated from your own application. No need to create or manage reader accounts in Document360.	Readers are managed through your organization's Identity Provider (IdP) such as Okta, Azure AD, or Google Workspace.
Login destination	Always redirects to the knowledge base site. Users cannot access the Document360 portal via JWT.	Can support both reader and team logins, depending on configuration.
When to use	Ideal if you do not have an IdP, or prefer to manage authentication in your own application.	Recommended if your organization already uses an IdP and wants centralized authentication and access control.
User registration flow	You control login and user provisioning in your own app.	Can support self-registration, password reset, and user lifecycle management depending on the IdP.
SSO login page	You define the Sign in URL and optionally the Sign out URL in JWT configuration settings.	The login page is handled by the IdP, and redirects are managed through SAML or OpenID settings.
Advanced features	Not supported: auto-register SSO readers, skipping Document360's sign-in page, reader self-registration.	Available depending on the IdP's capabilities.
Implementation	Simpler setup for developers. You generate the JWT, sign it using a client secret created in Document360, and handle authentication in your app.	Requires configuration of IdP metadata, certificates, and mappings with Document360.

How JWT authentication works

The diagram below shows the complete JWT authentication flow between your application, the Document360 identity server, and the knowledge base site.

Flowchart illustrating user authentication process with Document360 Identity Server and Customer App.

Key terminology

Term	Description
Login URL	A public login page in your application where users are redirected to authenticate.
Code generation URL	A secure backend endpoint in your app that sends user data to Document360 to obtain an authorization code.
Callback URL	The URL in Document360 where your app redirects the user after receiving the authorization code. This is auto-generated by Document360.

Authentication flow

User accesses the private knowledge base. Document360 detects that JWT SSO is enabled and redirects the user to the Sign in URL configured in JWT settings.
User logs in to your application. If the user is not already authenticated, your login page handles their authentication.
Your backend requests a one-time auth code. Your backend sends a POST request to the Code generation URL with the user's identity, optional readerGroupIds, and tokenValidity in minutes. This request must be authorized using HTTP Basic Auth with your Client ID and Client Secret.

Example Authorization Header

Authorization: Basic Base64Encode(clientId:clientSecret)

JSON Payload Example

{
  "username": "firstname + lastname",
  "firstName": "firstname",
  "lastName": "lastname",
  "emailId": "user email",
  "readerGroupIds": ["Obtain from Reader groups overview page in the Document360 portal (Optional)"],
  "tokenValidity": 15
}

NOTE

Ensure correct JSON syntax to avoid configuration errors.

Document360 Identity server returns an auth code. If the request is valid, Document360's identity server generates a single-use authorization code and sends it back to your backend.
Your app redirects the user back to Document360. Your backend appends the code to the Callback URL and redirects the user to it. For example: https://yourproject.document360.io/jwt/authorize?code=xyz

NOTE

The authentication code is a one-time use code and cannot be reused.

Document360 validates the code. Document360 sends it to the identity server via backchannel to exchange it for a JWT token.
Reader session is created. Document360 extracts user information and access rules based on readerGroupIds from the token. A session is created for the reader, granting them access to the allowed categories, languages, or versions.

Token validity and session behavior

You can define the session duration using the tokenValidity field in the payload (min: 5 minutes, max: 1440 minutes).
Once the token expires, the reader is redirected back to your Sign in URL.
If the user is still authenticated in your app, a new code is generated and the session is re-established seamlessly.

Get started with JWT

Article	Description
Configure JWT in Document360	Create your JWT configuration, set up project-level login settings, and generate your secret tokens.
Implement JWT in your application	Set up the backend redirect logic with code samples in C#, Node.js, and Java.
Test your JWT configuration	Verify your setup using cURL or Postman before going live.
Managing JWT configurations	Enable, disable, delete, and manage token rotation, domain routing, login page states, and audit logs.
JWT reader groups	Control which content readers can access by assigning them to reader groups via JWT.
Configure JWT for the knowledge base widget	Set up JWT authentication for your embedded knowledge base widget.
JWT for the AI chatbot	Secure your AI chatbot access using JWT authentication.

TIP

If you are setting up JWT for the first time, complete the steps in order: Configure JWT in Document360 → Implement JWT in your application → Test your JWT configuration.

FAQ

If a JWT user logs out of the client application, are they also logged out of Document360?

No. The session on Document360 is independent after the initial sign-in. Users can continue using Document360 until the token's validity expires, even after logging out of the client application. For example, if the token validity is set to 1 day, the Document360 session will remain active until the token expires.

Can I provide a token validity value outside the allowed range?

No. If a value outside the range is provided, the system automatically assigns the nearest allowed value: 5 minutes for values below the minimum, and 1440 minutes for values above the maximum.

What is the difference between JWT and SSO?

You can view a comparison between JWT (JSON Web Token) and SSO (Single Sign-On) in the table below:

Category	JWT (JSON Web Token)	SSO (Single Sign-On)
Authentication	Tokens generated per session or user request.	Centralized authentication across apps.
Token expiry	Tokens typically expire after a set period.	No token; session handled by identity provider.
Security	Requires secure token storage.	More secure; centralized credential storage.
Usage	Used for stateless, single-use authentication.	Used for multiple applications with a single login.
Integration	Easier to implement in custom apps.	Requires integration with an identity provider.

Can JWT and SSO (SAML or OpenID Connect) be active simultaneously?

Yes. JWT and SSO configurations can coexist in the same project without conflict. Each type is managed independently. Changes to one do not affect the other.

What should I do if secret tokens are lost?

Secret tokens are displayed only once at the time of configuration creation. If lost, navigate to the Edit configuration modal and click Regenerate for the relevant token. Regeneration immediately invalidates the existing token. Update your application with the new token without delay to avoid authentication failures.

Documentation Index

JWT