ReadMe Documentation

Welcome to the ReadMe Documentation, where you'll find comprehensive guides and community support to help you start working with ReadMe as quickly as possible!

Get Started

Using Custom Authentication

By using your own form of authentication, you can embed user data directly in your documentation.

There are three options for authentication. Users can either log in with a ReadMe account, click a JWT link, or using your own custom OAuth flow.

ReadMe Login

With a ReadMe login, users will be able to log into your site with their ReadMe accounts, which work across any site using ReadMe. You can use the "email" and "name" variables in your docs to personalize them to each user. Best part is, this requires no setup on your end at all! User session expires after 14 days for the admin panel and one year for the hub.

JWT Link

We support JWT as a way to securely log a user in and pass in information about them. JWT lets you send ReadMe a JSON blob about the user, and sign it on the server so that we know the data hasn't been tampered with.

It's really easy to set up! You can read more about it at There are packages available in dozens of languages to generate JWT links on your site. When a user clicks a link specific to them they are directed to ReadMe and automatically logged in.

Your JWT secret can be found under User Connect > Magic Login Link

const sign = require('jsonwebtoken').sign

exports.jwt = function(user) {
  // config.jwt_secret is provided by readme and used to sign the request
  const jwt = sign(user, config.jwt_secret);
  return "" + jwt;

More information about the user object can be found here: User Data in ReadMe

Linking to a specific page within a project must include a redirect as a query parameter in the URL. Example:

Custom OAuth 2.0

To allow your users to log in using custom authentication, it's possible to write custom OAuth code, with the final redirect using a JWT url to pass the user information to ReadMe.

This can be done by running an OAuth bridge server from ReadMe or on your own infrastructure. Starter code can be viewed on GitHub. For most OAuth implementations, editing config.js will be sufficient to get the OAuth bridge working. Documentation on the format for sending data via JWT can be found here: User Data in ReadMe

For an example of setting up a simple OAuth server, view Setting up Github OAuth.

Custom OAuth is an enterprise feature only, contact if you are interested!

User Session Expiration

You can set the number of minutes before the user will be required to reauthenticate under advanced options in variable defaults.

What's Next

Now that you have figured out which kind of authentication works best for you, the only other thing to understand is the format that we expect for your user data.

User Data in ReadMe

Using Custom Authentication

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.