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

User Data in ReadMe

User Data JSON Format

By sending JSON with a specific format to ReadMe (either through an oauth flow, or the user clicking a JWT link), you can tell ReadMe about your user embed information about them directly in the documentation.

For more information about how to pass this data into ReadMe, read Using Custom Authentication.

An example user object is defined below:

{
 name: "Marc Cuva",
 email: "marc@readme.io",
 isAdmin: true, // Optional
 isReadOnly: true, // Optional
 apiKey: '12345',
 version: 1, // Required, if omited things can break unexpectedly
}
{
 name: "Marc Cuva",
 email: "marc@readme.io",
 isAdmin: true, // Optional
 keys: [{
   apiKey: '12345',
   name: "Marc's 1st Project"
 }, {
   apiKey: '678910',
   name: "Marc's 2nd Project"
 }],
 version: 1,  // Required, if omited things can break unexpectedly
}

Any data that is passed into this object can be used as a variable. Though certain keys have specific meaning within ReadMe.

Variable
Use in ReadMe
Required?

name

Display name in upper right

Yes

email

Email associated with user, used in support forum among other places

Yes

isAdmin

Adds links to the dash, and allows access to disabled sections

No (default false)

isReadOnly

Allows user to access project with "Project Members Only" or "Site-wide password" access control turned on.

No (default false)

apiKey

Prefills API key for OAuth authentication in API explorer

No

user

Prefills basic auth username in API Explorer

No

pass

Prefills basic auth password in API Explorer

No

Using Variables in Documentation

The data passed in can be used as variables in the documentation. Just wrap the variable name with <<variable>> to users value, or the default if no value is set.

<<name>> will be replaced with "Marc Cuva" in the docs.

If a user is not logged in, and OAuth Login is set up, there will be a prompt on the default variable for the user to log in.

Using Variables in API Explorer

By setting specific variables in your user object, the API Explorer will automatically use those values when the user is logged in.

OAuth Authentication

If apiKey object is set (like in the example above), and the API Explorer is using OAuth Authentication the value will automatically be set.

OAuth token automatically set by `apiKey`

OAuth token automatically set by apiKey

Basic Auth

{
 name: "Marc Cuva",
 email: "marc@readme.io",
 isAdmin: true, // Optional
 user: 'username',
 pass: 'password',
 version: 1, // Required, if omited things can break unexpectedly
}
{
 name: "Marc Cuva",
 email: "marc@readme.io",
 isAdmin: true, // Optional
 keys: [{
   user: 'Marc 1'
   pass: 'Pass 1'
   name: "Marc's 1st Project"
 }, {
   user: 'Marc 2'
   pass: 'Pass 2'
   name: "Marc's 2nd Project"
 }],
 version: 1, // Required, if omited things can break unexpectedly
}

If the user object looks like this example, and the authentication is set to Basic Auth, the values will be automatically set the user and pass.

Basic Auth forms are filled from user object `user` and `pass`

Basic Auth forms are filled from user object user and pass

One User with Multiple Projects

In some cases one user will have multiple sets of data. For example, a user can be apart of several teams all with a unique API Key. To support this functionality, just pass an array into a keys object with all of the values specific to that project.

{
 name: "Marc Cuva",
 email: "marc@readme.io",
 isAdmin: true, // Optional
 keys: [{
   apiKey: '12345',
   user: 'Marc',
   pass: 'password',
   key: 'key1',
   name: "Marc's 1st Project" // Required, used to select a project
 }, {
   apiKey: '678910',
   user: 'Marc2',
   pass: 'password2',
   key: 'key2',
   name: "Marc's 2nd Project"
 }],
 version: 1,  // Required, if omited things can break unexpectedly
}

When a variable that has multiple values is used in the documentation, for example <<key>>, the variable will have a dropdown allowing the user to pick which of the projects they want to be active. This dropdown affects all of the variables on your site, so switching the current project on one variable will make sure all of the other ones remain consistent.

Project Switcher on a variable

Project Switcher on a variable

Setting Default Variables in the UI

In the variables section within User Controls, you can set default values for variables. If no user is logged in, these values will be used in the documentation.

In the above example, in the documentation for that project <<api_domain>> will be replaced with https://api.readme.io/v1/ when no user is logged in.