User Data Options
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 and embed information about them directly in the documentation.
For more information about how to pass this data into ReadMe, read Log Your Users In with a Custom Login Flow.
An example user object is defined below:
{
"name": "Marc Cuva",
"email": "[email protected]",
"isAdmin": true, // Optional
"isReadOnly": true, // Optional
"apiKey": "12345",
"version": 1, // Required, if omited things can break unexpectedly
"parameters": {
"x-readme-version": "1.0",
"slug": "getting-started"
}
}
{
"name": "Marc Cuva",
"email": "[email protected]",
"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
"allowedProjects": ["parent-project", "child-project"]
}
{
"name": "Marc Cuva",
"email": "[email protected]",
"keys": [
{
"apiKey": "12345",
"name": "Marc's 1st Project"
},
{
"apiKey": "678910",
"name": "Marc's 2nd Project"
}
],
"version": 1, // Required, if omited things can break unexpectedly
"allowedProjects": [
{ "subdomain": "child-project", "access": "readonly" },
{ "subdomain": "child-project-2", "access": "admin" }
]
}
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 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 Reference (this is not the ReadMe project API key!) | No |
user | Prefills Basic Auth username in the Authentication section of the API Reference | No |
pass | Prefills Basic Auth password in the Authentication section of the API Reference | No |
allowedProjects | Array of strings (subdomain) that you want to give access to. Or an array of objects with values { project: "subdomain", access: "readonly | admin" } | Yes |
parameters | Object of parameters present in the API Reference section. Values for keys entered here will be treated as default parameters in the API Reference. |
Using Variables in Documentation
The data passed in can be used as variables in the documentation. Just wrap the variable name with <<variable>> to user's 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.

Defining Defaults in the API Reference
By adding the parameters
object in the user object, you'll be able to pre-populate parameters on endpoints. Let's consider the following user object:
{
"name": "Marc Cuva",
"email": "[email protected]",
"parameters": {
"x-readme-version": "1.0",
"slug": "getting-started"
}
}
When the logged-in user with the above user data payload visits an endpoint in the API Reference section that has parameters with the IDs x-readme-version
or slug
present, for example, our Get Doc endpoint, the parameters will be pre-filled with the values defined.
Single Project Support
Auto-populating parameters currently only works for single-project. It will not work if the
parameters
object is added within thekeys
array.
Using Variables in API Reference Section
By setting specific variables in your user object, the API Reference section will automatically use those values when the user is logged in.
OAuth and API Key Authentication
If apiKey
is set in the passed in JSON object (like in the following example) and the API Reference section is using OAuth or API Key Authentication, the value will automatically be set.
{
"name": "Marc Cuva",
"email": "[email protected]",
"apiKey": "12345",
"version": 1 // Required, if omited things can break unexpectedly
}

OAuth token automatically set by apiKey
Basic Auth
{
"name": "Marc Cuva",
"email": "[email protected]",
"isAdmin": true, // Optional
"user": "user",
"pass": "pass",
"version": 1 // Required, if omited things can break unexpectedly
}
{
"name": "Marc Cuva",
"email": "[email protected]",
"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
Multiple security schemes
As an alternative to the above, you can also pass in values to the user object that have the same name as your OAS Security Schemes. So for the following securitySchemes
:
{
"oauth2Scheme": {
"type": "oauth2"
},
"basicScheme": {
"type": "http",
"scheme": "basic"
},
"apiKeyScheme": {
"type": "apiKey",
"in": "query",
"name": "apiKey"
},
"cookieApiKeyScheme": {
"type": "apiKey",
"in": "cookie",
"name": "apiKey"
}
}
You can pass in a user object like this:
{
"name": "Marc Cuva",
"email": "[email protected]",
"oauth2Scheme": "oauth-key",
"basicScheme": {
"user": "user",
"pass": "pass",
},
"apiKeyScheme": "api-key",
"cookieApiKeyScheme": "cookie-api-key",
"version": 1, // Required, if omited things can break unexpectedly
}
And all of your security inputs will be prefilled.
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": "[email protected]",
"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
Using Variables in the GraphQL Explorer
By setting specific variables in your user object, the GraphQL Explorer section will automatically use those values when the user is logged in. See GraphQL API Reference for more information about how you can get access to the beta.
OAuth Authentication
If graphql
is set in the passed in JSON object (like in the following example), we will prefill in a Bearer
Authentication
header.
{
"name": "Marc Cuva",
"email": "[email protected]",
"graphql": "dGhpcyBpcyBteSBiZWFyZXIgdG9rZW4=",
"version": 1 // Required, if omited things can break unexpectedly
}
Updated 6 months ago