Custom Login Page

Apidog allows you to protect your published API documentation with custom authentication. This guide walks you through configuring a custom login page that integrates with your existing authentication system using JWT (JSON Web Token).

Configuration Guide

Go to the visibility settings of the documentation site, select Custom Login Page, and fill in the following two fields:

JWT Secret: Used to verify the signature of the token. It must be the same as the secret your backend uses when issuing JWTs. You need to generate this secret yourself.

Login URL: When users access the online documentation site, they will be redirected to this URL. You must host a login page at this address and implement authentication and token generation on your backend.

This login page is not provided by Apidog — you need to build and host your own.

Authentication Workflow

JWT (JSON Web Token) is an open standard for user authentication. Your login system should follow the flow below:

A user visits the online documentation site published by Apidog (e.g., https://xxxxx.apidog.io);

The system automatically redirects them to your configured login page (e.g., http://localhost:3000);

The user enters their credentials and submits the form;

Your backend verifies the user credentials;

Upon successful authentication, your backend generates a JWT signed using your configured secret (e.g., pJRdFC3amihQdWbHvUXNZG9WzYdEGHao);

Then, redirect the user back to the documentation site (e.g., https://xxxxx.apidog.io) and include the token as a query parameter named auth_token as shown below.

Apidog will automatically validate the token. If successful, the user can access the documentation content.

The login flow is illustrated in the diagram below:

Key Requirements

When implementing your custom login page, keep these requirements in mind:

JWT Generation: JWTs must be generated by your backend and signed using the secret configured in Apidog

Token Transmission: The JWT must be passed back to the documentation site via the auth_token URL parameter

Automatic Validation: Apidog will automatically parse and validate the token signature

Flexible Domain: The documentation site URL can be either the default Apidog-provided address or a custom domain you configured

Session Duration

After successful authentication via your custom login page, the user's access session lasts for 30 days. During this period, users can access the documentation without re-authenticating. The session is stored as a browser cookie and expires automatically after 30 days.

Note

The session duration is currently fixed at 30 days and cannot be configured.

FAQ

What tech stack can I use for the login page?

There are no restrictions. As long as your backend can handle POST login requests and return a URL containing auth_token, it will work. Node.js, PHP, Python, Go, etc., are all supported.

Is there a sample project available?

How long does the login session last?

Configuration Guide#

Authentication Workflow#

Key Requirements#

Session Duration#

FAQ#

Configuration Guide

Authentication Workflow

Key Requirements

Session Duration

FAQ