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 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.
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 "https://yourproject.readme.io?auth_token=" + jwt; };
const sign = require('jsonwebtoken').signexports.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
Linking to a specific page within a project must include a redirect as a query parameter in the URL. Example: https://readme.readme.io?auth_token=XXXXX&redirect=/page-to-go-to
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 growth@readme.io 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.