Product Guide

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

Log Your Users in with a Custom Login Flow

Why Log Your Customers Into Your Docs?

Logging users into your ReadMe docs allows you to show custom, personalized, interactive information to each user, drastically improving their experience using your documentation. You can:

  • Automatically show each user their own API Keys in the API Explorer and elsewhere in the docs. To demonstrate: in our docs, we use the <<keys:user>> variable to show your ReadMe API Key (if you're logged in to these docs now, you'll see your key value: . If you just see the text "ReadMe API Key," then you're not logged in.)
  • Provide users with working code samples they can just copy and paste—no separate trip to your dashboard required.
  • Create interactive API documentation—users can call the API directly from the API Explorer.
  • Login is a prerequiste for some neat Developer Metrics features, for example, showing the user's API Logs directly in the documentation.

JWT Setup

Setting this up is easy if you're a developer! The flow is simple:

  1. User clicks the Login link in ReadMe and is directed to a Login page on your site.
  2. User logs in (or is already logged in).
  3. Your site creates a JWT redirect URL with the user's information.
  4. User is redirected to your documentation and logged into ReadMe!

This guide will go into setup details below, but if you would prefer to jump straight into an example, we have a GitHub repo to play around with here: readmeio/readme-custom-login-demo.

JWT Redirect

Once you have a logged in user, you will need to redirect to ReadMe with details about that user. We use JWT to achieve this, and there are packages to help in almost every language!

const sign = require('jsonwebtoken').sign;

exports.readmeLogin = function(req, res) {
  // User being logged into ReadMe
  const user = {
    name: 'Gilfoyle',
    email: '[email protected]',
    
    // OAS Security variables
    apiKey: { user: 'user', pass: 'pass' },
  };

  const auth_token = sign(user, 'ReadMe JWT Secret');
  const readmeUrl = 'https://docs.readme-url.com';

  return `${readmeUrl}?auth_token=${auth_token}`;
};

Once you have the user, you just need to call the JWT sign function with the user and the secret key from ReadMe (you can find this in your project at Configuration > Custom Login). This will give you a signed version of the user you can send to ReadMe via the auth_token query string.

Setting a Custom Login URL in ReadMe

Once you have your login flow set up, you will need to tell ReadMe where to direct users when they click the Login button. Under Configuration > Custom Login you can set a Login URL that users will be directed to via the Login button in your documentation!

Interested in using a custom login to make your documentation private? This is available for customers on our Enterprise plan! Send us an email at [email protected] to learn more.

Updated about 20 hours ago


What's Next

Now that you have a custom login set up, learn about what you can pass into ReadMe to make your users experience amazing!

User Data in ReadMe

Log Your Users in with a Custom Login Flow


Suggested Edits are limited on API Reference Pages

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