Depending on your Handshake method, your API will respond with either a raw JSON object or a signed JWT. The shape of the data is the same for both:

type UserInfo = {
  expiresAt?: number;
  groups?: string[];
  content?: Record<string, any>;
  apiPlaygroundInputs?: {
    header?: Record<string, any>;
    query?: Record<string, any>;
    cookie?: Record<string, any>;
    server?: Record<string, string>;
  };
};
​
expiresAt
number

The time at which this information should expire, in seconds since epoch. If the user loads the page and the current time is after this value, the stored data will be deleted.

For JWT Handshakes: This is not the same as the exp claim of the JWT. The exp claim determines when a JWT should no longer be considered valid, and should be set as low as possible. In this case, it can probably be set to 10 seconds or lower. The expiresAt field determines when retrieved data should be considered stale, and can be anywhere from one day to several weeks.

​
groups
string[]

A list of groups that the user belongs to. This will determine which pages should be shown to this user. If any of these groups is listed in the groups field of a page’s metadata, that page will be shown.

​
content
object

A bag of values that can be accessed from within MDX content using the userContext variable. For example, if you have supplied { firstName: 'Ronan' } as your content field, you can use the following in your MDX: Good morning, {userContext.firstName}!

​
apiPlaygroundInputs
object

User-specific values that will be prefilled in the API playground if supplied. For example, if each of my customers makes requests at a specific subdomain, I can send { server: { subdomain: 'foo' } } as my apiPlaygroundInputs field, and this value will be prefilled on any API page with this subdomain value.

Theheader, query, and cookie fields will only be prefilled if they are part of your security scheme. Creating a standard header parameter named Authorization is not sufficient to enable this feature. To know if a field will be prefilled, navigate to your existing docs and check if the field is in either the Authorization or Server section.

Was this page helpful?

OAuth 2.0 HandshakeCustom Domain