Authentication

Securely authenticate your users and protect your API endpoints with API keys, OAuth 2.0, or JSON Web Tokens.

Mintlify supports three authentication strategies out of the box. Every request to a protected route must include a valid credential in the Authorization header. This guide walks through each method, when to use it, and how to rotate keys safely.

API Keys #

API keys are the simplest way to authenticate machine-to-machine requests. Generate a key in the dashboard, store it in an environment variable, and pass it as a bearer token:

        bash
        
          Copy

# Install the Mintlify CLI
npm install -g @mintlify/cli

# Set your secret key
export MINTLIFY_API_KEY="mk_live_9f2a4c8b1e7d"

# Make an authenticated request
curl https://api.mintlify.com/v1/users \
  -H "Authorization: Bearer $MINTLIFY_API_KEY" \
  -H "Content-Type: application/json"

Treat keys like passwords

Never commit API keys to version control. Use a secrets manager or environment variables loaded at runtime, and rotate keys every 90 days.

OAuth 2.0 #

For applications that act on behalf of end users, use the OAuth 2.0 authorization code flow with PKCE. Mintlify handles token exchange and refresh automatically.

Authorization flow

Redirect the user to https://auth.mintlify.com/authorize with your client_id and a PKCE challenge.
The user consents on Mintlify's hosted page — no UI for you to build.
Mintlify redirects back to your redirect_uri with a single-use code.
Exchange the code at /oauth/token for an access token and refresh token.

Always use PKCE

Public clients (SPAs, mobile apps) must use PKCE. Omitting it leaves your authorization code vulnerable to interception on shared devices.

Token reference #

Every authentication response returns the following fields. Tokens are opaque to the client and validated server-side.

Field	Type	Description
`access_token`	string	Short-lived credential used to authenticate API requests. Expires in `3600` seconds.
`refresh_token`	string	Long-lived credential used to obtain new access tokens without re-prompting the user.
`token_type`	string	Always `"Bearer"`. Included for OAuth 2.0 spec compliance.
`expires_in`	number	Lifetime of the access token in seconds.
`scope`	string	Space-separated list of granted permission scopes.

Key rotation #

Rotate keys with zero downtime by overlapping the old and new key for a grace period. See the versioning guide for the full rotation playbook.