ReadMe

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!

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 jwt.io. 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.

You can get your project's secret key in the dashboard under User Controls -> Auto Login.

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 "https://yourproject.readme.io?auth_token=" + jwt;
};

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

Custom OAuth

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 growth@readme.io if you are interested!


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