Set up JWT
Self-managed authentication integrated with your login system
With JWT, you manage the entire auth flow. This involves building and signing a fern_token cookie that integrates your docs with your existing login system. Like OAuth, JWT enables:
- Login only — gate docs behind authentication
- RBAC — restrict content by user role
- API key injection — pre-fill API keys in the API Explorer
How it works
- A user clicks Login on your docs site and is redirected to your authentication page.
- After authentication, your system signs a JWT with a secret key from Fern and sets it as a
fern_tokencookie. - Fern reads the token to determine the user’s access and credentials.
Architecture diagram
Configuration
Get your secret key
Reach out to Fern to get your secret key and send them the URL of your authentication page. This is where users are redirected after clicking Login.
Build the fern claim
The JWT payload must include a fern claim. What you include in the token’s fern claim controls which features are enabled: login only, RBAC, or API key injection.
Set the fern_token cookie
Add logic to your service to sign the JWT and set it as a fern_token cookie when a user logs in.
Example: Complete callback endpoint
This Next.js endpoint handles the callback from your authentication page. It reads the state parameter to determine where to redirect the user, mints a fern_token JWT using jose, sets it as a cookie, and redirects the user back to the docs.
Enable RBAC or API key injection (optional)
Once your fern_token is working, configure the features you need:
- Role-based access control — define roles in
docs.ymland restrict navigation items or page content by role. - API key injection — configure the
playgroundpayload, including custom headers, multiple API keys, and per-environment credentials.