-### Add custom domain
-
-Once the worker is created, click `Configure worker`. Navigate to the worker
-`Settings > Triggers`. Click on `Add Custom Domain` to add your desired domain
-into the list - we recommend you add both the version with and without `www.`
-prepended to the domain.
+2. Configure Domain
+ - Go to `Configure worker > Settings > Triggers`
+ - Add your domain via `Add Custom Domain`
+ - Add both `domain.com` and `www.domain.com` versions
-- -
- 
-
-
-## Getting Started
-
-Welcome! Follow the instructions below to learn how to deploy, update and
-supercharge your documentation with Mintlify.
-
-### Creating the Repository
-
-Mintlify docs are rendered from MDX files and configurations defined in our
-[starter kit](https://github.com/mintlify/starter). We use GitHub to integrate
-your docs with your code, and make source control effortless. Onboard through the [dashboard](https://dashboard.mintlify.com) or clone our [starter kit](https://github.com/mintlify/starter) to get started.
-
-
- 
-
-
@@ -112,45 +66,32 @@ export const MyComponent = ({ title }) => (
```
- MDX does not compile inside the body of an arrow function. Stick to HTML
- syntax when you can or use a default export if you need to use MDX.
+ Use HTML syntax in arrow functions - MDX won't compile here.
-2. Import the snippet into your destination file and pass in the props
-
+Use it:
```typescript destination-file.mdx
----
-title: My title
-description: My Description
----
-
import { MyComponent } from '/snippets/custom-component.mdx';
-Lorem ipsum dolor sit amet.
-
- This is the documentation for the JWT **Authentication** Handshake. The steps for setting up the [JWT **Personalization** Handshake](/settings/authentication-personalization/personalization-setup/jwt) are slightly different.
+ This guide covers JWT **Authentication**. For JWT **Personalization**, see the [JWT Personalization guide](/settings/authentication-personalization/personalization-setup/jwt).
-If you don’t have a dashboard, or if you want to keep your dashboard and docs completely separate, you can use your own login flow to authenticate users via a JWT in the URL.
+Use JWT authentication when you want to manage user authentication through your own login flow instead of the Mintlify dashboard.
-## Implementation
+## Setup Steps
-
- Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and generate a private key. Store this key somewhere secure where it can be accessed by your backend.
+
+ Generate a private key in your [Mintlify dashboard](https://dashboard.mintlify.com/products/authentication). Store this securely for your backend.
-
- Create a login flow that does the following:
+
+ Your login flow needs to:
- Authenticate the user
- - Create a JWT containing the authenticated user's info in the [User](../sending-data) format
- - Sign the JWT with the secret key, using the EdDSA algorithm
- - Create a redirect URL back to the `/login/jwt-callback` path of your docs, including the JWT as the hash
+ - Create a JWT with user info using the [User](../sending-data) format
+ - Sign it with EdDSA and your private key
+ - Redirect to `/login/jwt-callback` with the JWT as the hash
-
- Return to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and add the login URL to your Authentication settings.
+
+ Add your login URL to your [Mintlify authentication settings](https://dashboard.mintlify.com/products/authentication).
-## Example
+## Code Example
-I want to set up authentication for my docs hosted at `docs.foo.com`. I want my docs
-to be completely separate from my dashboard (or I don’t have a dashboard at all).
-
-To set up authentication with Mintlify, I go to my Mintlify dashboard and generate a
-JWT secret. I create a web URL `https://foo.com/docs-login` that initiates a login flow
-for my users. At the end of this login flow, once I have verified the identity of the user,
-I create a JWT containing the user’s custom data according to Mintlify’s specification.
-I use a JWT library to sign this JWT with my Mintlify secret, create a redirect URL of the
-form `https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}`, and redirect the user.
-
-I then go to the Mintlify dashboard settings and enter `https://foo.com/docs-login` for the
-Login URL field.
-
-Here's what the code might look like:
+Here's how to implement the JWT flow:
```ts TypeScript
@@ -55,7 +42,7 @@ const signingKey = await jose.importPKCS8(process.env.MINTLIFY_PRIVATE_KEY, 'EdD
export async function handleRequest(req: Request, res: Response) {
const user = {
- expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000), // 2 week session expiration
+ expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000), // 2 week session
groups: res.locals.user.groups,
content: {
firstName: res.locals.user.firstName,
@@ -65,7 +52,7 @@ export async function handleRequest(req: Request, res: Response) {
const jwt = await new jose.SignJWT(user)
.setProtectedHeader({ alg: 'EdDSA' })
- .setExpirationTime('10 s') // 10 second JWT expiration
+ .setExpirationTime('10 s') // JWT expires in 10s
.sign(signingKey);
return res.redirect(`https://docs.foo.com/login/jwt-callback#${jwt}`);
@@ -85,8 +72,8 @@ private_key = os.getenv(MINTLIFY_JWT_PEM_SECRET_NAME, '')
async def return_mintlify_auth_status(current_user):
jwt_token = jwt.encode(
payload={
- 'exp': int((datetime.now() + timedelta(seconds=10)).timestamp()), # 10 second JWT expiration
- 'expiresAt': int((datetime.now() + timedelta(weeks=2)).timestamp()), # 1 week session expiration
+ 'exp': int((datetime.now() + timedelta(seconds=10)).timestamp()), # JWT expires in 10s
+ 'expiresAt': int((datetime.now() + timedelta(weeks=2)).timestamp()), # 2 week session
'groups': ['admin'] if current_user.is_admin else [],
'content': {
'firstName': current_user.first_name,
@@ -99,4 +86,4 @@ async def return_mintlify_auth_status(current_user):
return RedirectResponse(url=f'https://docs.foo.com/login/jwt-callback#{jwt_token}', status_code=302)
```
-
+
\ No newline at end of file
diff --git a/settings/authentication-personalization/authentication-setup/oauth.mdx b/settings/authentication-personalization/authentication-setup/oauth.mdx
index 45206968c..bf6e7f2d2 100644
--- a/settings/authentication-personalization/authentication-setup/oauth.mdx
+++ b/settings/authentication-personalization/authentication-setup/oauth.mdx
@@ -1,49 +1,45 @@
---
title: 'OAuth 2.0 Handshake'
-description: 'Integrate with your OAuth server to enable user login via the Authorization Code flow'
+description: 'Set up user login with OAuth Authorization Code flow'
---
- This is the documentation for the OAuth **Authentication** Handshake. The steps for setting up the [OAuth **Personalization** Handshake](/settings/authentication-personalization/personalization-setup/oauth) are slightly different.
+ This guide covers OAuth **Authentication** Handshake setup. For [OAuth **Personalization** Handshake](/settings/authentication-personalization/personalization-setup/oauth) setup, see the separate guide.
-If you have an existing OAuth server, you can integrate with Mintlify for a seamless login experience.
-
-## Implementation
+## Setup Steps
-
- Go to your [Mintlify authentication settings](https://dashboard.mintlify.com/products/authentication), select the OAuth option, and fill out the required fields:
-
- - **Authorization URL**: The base URL for the authorization request, to which we will add the appropriate query parameters.
- - **Client ID**: An ID for the OAuth 2.0 client to be used.
- - **Scopes**: An array of scopes that will be requested.
- - **Token URL**: The base URL for the token exchange request.
- - **Info API URL** (optional): The endpoint that will be hit to retrieve user info. If omitted, the OAuth flow will only be used to verify identity, and the user info will be empty.
+
+ Head to your [Mintlify authentication settings](https://dashboard.mintlify.com/products/authentication) and select OAuth. Fill in:
+
+ - **Authorization URL** - Your auth request base URL
+ - **Client ID** - Your OAuth client ID
+ - **Scopes** - Required OAuth scopes
+ - **Token URL** - Your token exchange URL
+ - **Info API URL** (optional) - Endpoint for fetching user data
-
- Copy the Redirect URL listed in the [Mintlify authentication settings](https://dashboard.mintlify.com/products/authentication) and add it as an authorized redirect URL for your OAuth server.
+
+ Copy the Redirect URL from your Mintlify settings and add it to your OAuth server's allowed redirects.
-
- If you want to take advantage of authentication's customization features, you'll need to create an endpoint to retrieve info about your users.
- Create an API endpoint that can be accessed with an OAuth access token, and responds with a JSON payload following the [User](../sending-data) format.
-
- Return to your [Mintlify authentication settings](https://dashboard.mintlify.com/products/authentication) and add the Info API URL
- to your OAuth configuration.
+
+ To enable user customization:
+ 1. Create an endpoint accessible with OAuth tokens
+ 2. Return user data in [User](../sending-data) format
+ 3. Add your endpoint URL to Mintlify's OAuth settings
-## Example
-
-I have an existing OAuth server that supports the Authorization Code flow. I want to set up authentication for my docs hosted at `foo.com/docs`.
-
-To set up authentication with Mintlify, I create an endpoint `api.foo.com/docs/user-info` which requires an OAuth access token with the `docs-user-info` scope, and responds with the user's custom data according to Mintlify’s specification.
+## Example Configuration
-I then go to the Mintlify dashboard settings, navigate to the Authentication settings, select OAuth, and enter the relevant values for the OAuth flow and Info API endpoint:
-- **Authorization URL**: `https://auth.foo.com/authorization`
-- **Client ID**: `ydybo4SD8PR73vzWWd6S0ObH`
-- **Scopes**: `['docs-user-info']`
-- **Token URL**: `https://auth.foo.com/exchange`
-- **Info API URL**: `https://api.foo.com/docs/user-info`
+```json
+{
+ "Authorization URL": "https://auth.foo.com/authorization",
+ "Client ID": "ydybo4SD8PR73vzWWd6S0ObH",
+ "Scopes": ["docs-user-info"],
+ "Token URL": "https://auth.foo.com/exchange",
+ "Info API URL": "https://api.foo.com/docs/user-info"
+}
+```
-Finally, I copy the Redirect URL displayed in the dashboard settings and add it as an authorized redirect URL in my OAuth client configuration settings.
+The Info API endpoint (`api.foo.com/docs/user-info`) requires an OAuth token with `docs-user-info` scope and returns user data matching Mintlify's spec.
\ No newline at end of file
diff --git a/settings/authentication-personalization/personalization-setup/oauth.mdx b/settings/authentication-personalization/personalization-setup/oauth.mdx
index d786a042f..8b5ecbb5d 100644
--- a/settings/authentication-personalization/personalization-setup/oauth.mdx
+++ b/settings/authentication-personalization/personalization-setup/oauth.mdx
@@ -1,45 +1,49 @@
---
title: 'OAuth 2.0 Handshake'
-description: 'Integrate with your OAuth server to enable user login via the PKCE flow'
+description: 'Enable user login via OAuth PKCE flow'
---
- This is the documentation for the OAuth **Personalization** Handshake. The steps for setting up the [OAuth **Authentication** Handshake](/settings/authentication-personalization/authentication-setup/oauth) are slightly different.
+ This guide covers OAuth **Personalization** Handshake. For OAuth **Authentication** setup, see [this guide](/settings/authentication-personalization/authentication-setup/oauth).
-If you have an existing OAuth server that supports the PKCE flow, you can integrate with Mintlify for a seamless login experience.
-
-## Implementation
+## Setup Guide
-
- Create an API endpoint that can be accessed with an OAuth access token, and responds with a JSON payload following the [User](../sending-data) format. Take note of the scope or scopes required to access this endpoint.
+
+ Build an endpoint that:
+ - Accepts OAuth access tokens
+ - Returns user data in [User](../sending-data) format
+ - Note the required scopes
-
- Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication), select the OAuth option, and fill out the required fields:
-
- - **Authorization URL**: The base URL for the authorization request, to which we will add the appropriate query parameters.
- - **Client ID**: An ID for the OAuth 2.0 client to be used.
- - **Scopes**: An array of scopes that will be requested.
- - **Token URL**: The base URL for the token exchange request.
- - **Info API URL**: The endpoint that will be hit to retrieve user info.
+
+ In your [dashboard settings](https://dashboard.mintlify.com/products/authentication):
+ - Choose OAuth
+ - Fill in:
+ - Authorization URL
+ - Client ID
+ - Scopes
+ - Token URL
+ - Info API URL
-
- Copy the Redirect URL listed in the [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and add it as an authorized redirect URL for your OAuth server.
+
+ Copy the Redirect URL from your dashboard and add it to your OAuth server's allowed redirects.
-## Example
-
-I have an existing OAuth server that supports the PKCE flow. I want to set up authentication for my docs hosted at `foo.com/docs`.
-
-To set up authentication with Mintlify, I create an endpoint `api.foo.com/docs/user-info` which requires an OAuth access token with the `docs-user-info` scope, and responds with the user's custom data according to Mintlify’s specification.
-
-I then go to the Mintlify dashboard settings, navigate to the Personalization settings, select OAuth, and enter the relevant values for the OAuth flow and Info API endpoint:
-- **Authorization URL**: `https://auth.foo.com/authorization`
-- **Client ID**: `ydybo4SD8PR73vzWWd6S0ObH`
-- **Scopes**: `['docs-user-info']`
-- **Token URL**: `https://auth.foo.com/exchange`
-- **Info API URL**: `https://api.foo.com/docs/user-info`
-
-Finally, I copy the Redirect URL displayed in the dashboard settings and add it as an authorized redirect URL in my OAuth client configuration settings.
+## Quick Example
+
+Let's say you have docs at `foo.com/docs`:
+
+1. Create endpoint `api.foo.com/docs/user-info` that needs scope `docs-user-info`
+2. Configure OAuth in dashboard:
+```json
+{
+ "authorizationUrl": "https://auth.foo.com/authorization",
+ "clientId": "ydybo4SD8PR73vzWWd6S0ObH",
+ "scopes": ["docs-user-info"],
+ "tokenUrl": "https://auth.foo.com/exchange",
+ "infoApiUrl": "https://api.foo.com/docs/user-info"
+}
+```
+3. Add the Redirect URL to your OAuth server config
\ No newline at end of file
diff --git a/settings/authentication-personalization/personalization-setup/shared-session.mdx b/settings/authentication-personalization/personalization-setup/shared-session.mdx
index 5066952c1..f99fd772d 100644
--- a/settings/authentication-personalization/personalization-setup/shared-session.mdx
+++ b/settings/authentication-personalization/personalization-setup/shared-session.mdx
@@ -1,54 +1,53 @@
---
title: 'Shared Session Handshake'
-description: 'Seamlessly share user sessions between your dashboard and your docs'
+description: 'Share user sessions between your dashboard and docs'
---
- This is the documentation for the Shared Session **Personalization** Handshake. The Shared Session Handshake is not available for Authentication.
+ This documentation covers the Shared Session **Personalization** Handshake only. Not available for Authentication.
-This method utilizes the session authentication info already stored in your user’s browser to create a seamless documentation experience.
+Uses existing session authentication from your user's browser for seamless docs integration.
-## Implementation
+## Setup
-
- Create an API endpoint that uses session authentication to identify users, and responds with a JSON payload following the [User](../sending-data) format.
-
- If the API domain does not *exactly match* the docs domain:
- - Add the docs domain to your API's `Access-Control-Allow-Origin` header (must not be `*`)
- - Ensure your API’s `Access-Control-Allow-Credentials` header is `true`
-
- These CORS options only need to be enabled on the *single endpoint* responsible for returning user information. We do not recommend enabling these options on all dashboard endpoints.
-
+
+ Build an API endpoint that:
+ - Uses your session auth to identify users
+ - Returns JSON in the [User](../sending-data) format
+
+ If API and docs domains differ:
+ ```bash
+ # Required CORS headers (only for user info endpoint)
+ Access-Control-Allow-Origin: your-docs-domain.com
+ Access-Control-Allow-Credentials: true
+ ```
-
- Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and add the API URL and your Login URL to your Personalization settings.
+
+ Add your API URL and Login URL in your [Mintlify dashboard](https://dashboard.mintlify.com/products/authentication).
-## Examples
-
-### Dashboard at subdomain, docs at subdomain
-
-I have a dashboard at `dash.foo.com`, which uses cookie-based session authentication. My dashboard API routes are hosted at `dash.foo.com/api`. I want to set up authentication for my docs hosted at `docs.foo.com`.
-
-To set up authentication with Mintlify, I create another dashboard endpoint `dash.foo.com/api/docs/user-info` which identifies the user using session auth, and responds with their custom data according to Mintlify’s specification. I then add `https://docs.foo.com` to the `Access-Control-Allow-Origin` allow-list **for this route only**, and ensure my `Access-Control-Allow-Credentials` configuration is set to `true` **for this route only**.
-
-I then go to the Mintlify dashboard settings and enter `https://dash.foo.com/api/docs/user-info` for the API URL field.
-
-### Dashboard at subdomain, docs at root
-
-I have a dashboard at `dash.foo.com`, which uses cookie-based session authentication. My dashboard API routes are hosted at `dash.foo.com/api`. I want to set up authentication for my docs hosted at `foo.com/docs`.
-
-To set up authentication with Mintlify, I create another dashboard endpoint `dash.foo.com/api/docs/user-info` which identifies the user using session auth, and responds with their custom data according to Mintlify’s specification. I then add `https://foo.com` to the `Access-Control-Allow-Origin` allow-list **for this route only**, and ensure my `Access-Control-Allow-Credentials` configuration is set to `true` **for this route only**.
-
-I then go to the Mintlify dashboard settings and enter `https://dash.foo.com/api/docs/user-info` for the API URL field.
-
-### Dashboard at root, docs at root
-
-I have a dashboard at `foo.com/dashboard`, which uses cookie-based session authentication. My dashboard API routes are hosted at `foo.com/api`. I want to set up authentication for my docs hosted at `foo.com/docs`.
-
-To set up authentication with Mintlify, I create another dashboard endpoint `foo.com/api/docs/user-info` which identifies the user using session auth, and responds with their custom data according to Mintlify’s specification.
-
-I then go to the Mintlify dashboard settings and enter `https://foo.com/api/docs/user-info` for the API URL field.
\ No newline at end of file
+## Common Setups
+
+### Subdomain to Subdomain
+Dashboard: `dash.foo.com` → Docs: `docs.foo.com`
+```bash
+API Endpoint: https://dash.foo.com/api/docs/user-info
+CORS Origin: https://docs.foo.com
+```
+
+### Subdomain to Root
+Dashboard: `dash.foo.com` → Docs: `foo.com/docs`
+```bash
+API Endpoint: https://dash.foo.com/api/docs/user-info
+CORS Origin: https://foo.com
+```
+
+### Root to Root
+Dashboard: `foo.com/dashboard` → Docs: `foo.com/docs`
+```bash
+API Endpoint: https://foo.com/api/docs/user-info
+# No CORS needed - same domain
+```
\ No newline at end of file
diff --git a/settings/gitlab.mdx b/settings/gitlab.mdx
index 01c0b82bf..ee6b3f48d 100644
--- a/settings/gitlab.mdx
+++ b/settings/gitlab.mdx
@@ -4,90 +4,60 @@ description: "Sync your docs with a GitLab repo"
icon: "gitlab"
---
-We use a combination of Access tokens and Webhooks to authenticate and sync
-changes between GitLab and Mintlify.
-
-- We use Access tokens to pull information from GitLab.
-- We use Webhooks so GitLab can notify Mintlify when changes are made.
- - This allows Mintlify to create preview deployments when a MR is created.
+Mintlify uses Access tokens for authentication and Webhooks for sync notifications between GitLab and Mintlify.
## Set up the connection
- Within your GitLab project, navigate to `Settings` > `General` and find the `Project ID`.
+ Go to `Settings` > `General` and copy your `Project ID`.
-
- a. Navigate to `Settings` > `Access Tokens`.
-
- b. Select `Add new token`.
- 1. Name the token "Mintlify".
- 2. If you have a private repo, you must set the role as `Maintainer`.
- 3. Choose `api` and `read_api` for the scopes.
-
- c. Finally click `Create project access token` and copy the token.
-
+
+ Navigate to `Settings` > `Access Tokens` and create a new token:
+ - Name: "Mintlify"
+ - Role: `Maintainer` (required for private repos)
+ - Scopes: `api` and `read_api`
+
+ Click `Create project access token` and copy it.
-
-
- Within the [Mintlify dashboard](https://dashboard.mintlify.com/settings/deployment/git-settings), add the project ID and access token from the previous steps alongside the other configurations. Click "Save Changes" when you're done.
+
+ Add your project ID and access token in the [Mintlify dashboard](https://dashboard.mintlify.com/settings/deployment/git-settings).
-## Create the webhook
-
-Webhooks allow us to receive events when changes are made so that we can
-automatically trigger deployments.
+## Add webhook
-
+
+ Go to `Settings` > `Webhooks` > `Add new Webhook`
-
- In the "URL" field, enter the endpoint `https://leaves.mintlify.com/gitlab-webhook` and name the webhook "Mintlify".
-
-
-
- Paste the Webhook token generated after setting up the connection.
-
- 
-
-
-
- Select the events you want to trigger the webhook:
- - Push events (All branches)
- - Merge requests events
-
- When you're done it should look like this:
+
+ - URL: `https://leaves.mintlify.com/gitlab-webhook`
+ - Name: "Mintlify"
+ - Token: Copy from Mintlify dashboard
+ - Events: Enable "Push events" and "Merge requests events"
-
- After creating the Webhook, click the "Test" dropdown and select "Push events" to send a sample payload to ensure it's configured correctly. It'll say "Hook executed successfully: HTTP 200" if configured correctly.
-
- This will help you verify that everything is working correctly and that your documentation will sync properly with your GitLab repository.
+
+ Click "Test" > "Push events". You should see "Hook executed successfully: HTTP 200".
-
-
- Reach out to the Mintlify team if you need help. Contact us
- [here](https://mintlify.com/enterprise).
-
-
-[git-settings]: https://dashboard.mintlify.com/settings/deployment/git-settings
+Need help? [Contact us](https://mintlify.com/enterprise).
\ No newline at end of file
-
-
-
-