Credentials and security

How Mintlify handles integration credentials and what to keep in mind.

Integration credentials in Mintlify live in docs.json in your repository. Understanding how they’re exposed helps you choose the right level of access when generating keys.

How credentials are used

When a reader loads a page on your docs site, Mintlify renders your docs.json configuration and injects integration scripts into the page HTML. This means credentials in the integrations section of docs.json are included in the page source — they’re client-side values.

This is the expected behavior for analytics and tracking integrations, which are designed to be used in the browser. The keys you add to docs.json should be public write-only tokens, not secret API keys with read access to your data.

Never put secret or read-access API keys in docs.json. Use only public project tokens or measurement IDs — the same credentials you would embed in a JavaScript snippet on any public website.

Generating the right kind of key

Provider	What to use
Google Analytics 4	Measurement ID (starts with G-) — always public
PostHog	Project API key (starts with phc_) — public write-only
Mixpanel	Project token — public write-only
Segment	Write key — public write-only, scoped to one source
Hotjar	Site ID (hjid) — always public

Private docs and authentication

If your Mintlify site requires reader authentication (login to view), you can restrict access through Mintlify’s authentication settings. This is separate from integration credentials — it controls who can see your docs, not how tracking keys are stored.

See Mintlify’s authentication documentation for SSO, password protection, and token-based access options.

Rotating credentials

If a credential is compromised:

1. Generate a new key in the provider’s dashboard.
2. Update docs.json with the new value.
3. Push the change — Mintlify deploys automatically.
4. Revoke the old key in the provider’s dashboard after confirming the new one works.