MintlifyでプライベートAPIドキュメントのアクセス制限とユーザー認証を設定する方法

有償パートナー、大企業クライアント、社内他部門向けにプライベートAPIやSDKドキュメントを管理・提供するエンジニアリングチームは、セキュリティと開発者体験のトレードオフという課題に直面します。API仕様の理解を深めるためには、MintlifyのMDXおよびOpenAPIエンジンを活かしたインタラクティブなAPIリファレンスやテスト用プレイグラウンド（Playground）が不可欠ですが、同時に決済や管理に関わる機密エンドポイントを公開スクレイパーや未認証ユーザーから厳格に遮断しなければなりません。

Mintlifyは、この要件を満たすために4つのアクセス制御方式を提供しています。組織内限定アクセス、パスワード保護、エンタープライズ向けシングルサインオン（SSO / OAuth 2.0）、そして署名付きJWT（JSON Web Token）認証です。本ガイドでは、アーキテクチャ上の前提条件、設定ワークフロー、MDXフロントマターによるグループ別ロールベースアクセス制御（RBAC）、およびAPIプレイグラウンドの安全な認証情報自動入力手順を詳しく解説します。

アーキテクチャの前提条件とドメイン制約

認証方式を設定する前に、Mintlifyがアクセス制御コンテンツを配信する際の前提条件を確認する必要があります。

1. 独自ドメイン運用の必須条件： 全体認証・部分認証を問わず、認証ゲート機能を利用するには、専用のカスタムドメイン（例: docs.api.example.com）またはMintlifyのサブドメイン（例: example.mintlify.site）でのホスティングが必要です。サブパス運用（例: example.com/docs）でのゲートアクセス認証はサポートされていません。サブパス環境では、強制的なアクセス遮断を行わないパーソナライゼーション機能のみが利用可能です。
2. アクセス制限の適用範囲（全体認証 vs. 部分認証）： チームの要件に応じて、サイト全体をログイン必須にする**全体認証（Full Authentication）と、クイックスタートや共通ガイドは公開したまま機密エンドポイントのみを遮断する部分認証（Partial Authentication）**を選択できます。
3. プレビューデプロイのセキュリティ： Git連携によってプルリクエストごとに自動生成されるプレビューURLは、未保護のまま放置すると機密エンドポイントの漏洩経路になります。Mintlifyダッシュボードで認証を有効にすると、すべてのプレビュー環境にも同一の保護ルールが自動適用されます。

認証方式の比較マトリクス

方法1：パスワード保護（手軽な一時的アクセス制限）

初期の顧客パイロット検証や機密保持契約（NDA）下のステージング確認など、短期間でアクセスを制限したい場合は、パスワード保護が最も迅速な選択肢です。

設定手順

1. Mintlifyダッシュボードにアクセスし、対象プロジェクトの Access タブを開きます。
2. Visibility を Public から Private に変更します。
3. Method で Password を選択します。
4. 十分な強度の共有パスワードを入力し、Save changes をクリックします。

メリットと限界

設定自体は数分で完了しますが、全閲覧者が単一のパスワードを共有するため、個々のユーザー操作の監査ログを取得することはできません。また、特定パートナーのアクセス権のみを剥奪することはできず、パスワードを変更すると全員に影響が及びます。そのため、本番環境の長期運用ではなく、暫定的なテスト環境での利用に限定することを推奨します。

方法2：企業向けSSOとOAuth 2.0（IDフェデレーション連携）

社内開発者向けポータルや大企業顧客との専用連携では、SAML 2.0やOAuth 2.0を用いて既存のIDプロバイダー（IdP）と連携させることで、コンプライアンス遵守と即時アクセス剥奪を実現します。

Okta SAML 2.0 連携手順

1. Mintlify側エンドポイントの取得： Mintlifyダッシュボードの Security ページへ進み、Configure をクリックして Okta SAML を選択します。表示された Single sign on URL（ACS URL）と Audience URI（SP Entity ID）をコピーします。
2. Okta管理画面でSAMLアプリを作成： Okta管理コンソールで Applications > Create App Integration > SAML 2.0 を選択し、先ほどコピーしたURLとURIを貼り付けます。
3. 属性ステートメントのマッピング： Mintlifyが要求する属性を以下のようにマッピングします。
   • firstName -> user.firstName
   • lastName -> user.lastName
   • Name -> user.email（Name IDフォーマットは EmailAddress を指定）
4. メタデータURLの登録： Oktaから Metadata URL を取得し、Mintlifyの管理画面に貼り付けて Save changes をクリックします。

設定完了後、ドキュメントURLにアクセスしたユーザーは自動的に企業のIdP認証画面へリダイレクトされ、認証成功後にのみAPI仕様が閲覧可能になります。

方法3：JWTによるカスタム認証（自社アプリとのシームレス連携）

有償SaaSや開発者プラットフォームでは、ユーザーはすでに自社サービスのダッシュボードにログインしています。ドキュメント閲覧時に再ログインを要求しないシームレスな移行を実現するため、Mintlifyは非対称鍵署名を用いたJWT連携をサポートしています。

アーキテクチャフロー

ブラウザ (ユーザー)             自社バックエンド (API/Web)          Mintlify ドキュメント
     |                                |                                   |
     | 1. 「APIドキュメント」をクリック  |                                   |
     |------------------------------->|                                   |
     |                                | 2. ユーザー属性・グループを格納し、  |
     |                                |    ES256秘密鍵でJWTに署名         |
     | 3. ドキュメントURLへリダイレクト  |                                   |
     |    https://docs.example.com/#JWT|                                  |
     |<-------------------------------|                                   |
     |                                                                    |
     | 4. URLハッシュにJWTを付与してドキュメントをリクエスト                  |
     |------------------------------------------------------------------->|
     |                                | 5. ES256署名を検証し、             |
     |                                |    権限を適用してURL履歴から消去    |
     | 6. 許可されたエンドポイントと入力済みPlaygroundを表示                 |
     |<-------------------------------------------------------------------|

実装手順

1. Mintlifyダッシュボードの Access（または Personalization）で JWT を選択し、自社サービスのログインURLを登録します。
2. ダッシュボードで暗号鍵ペアを生成し、発行された秘密鍵を安全な環境（AWS Secrets ManagerやKMSなど）に保存します。
3. 自社のバックエンドサービスで、有効期限やグループ属性を含むペイロードを作成し、ES256 アルゴリズムで署名します。

import jwt from "jsonwebtoken";

// Node.jsによるMintlify認証トークン生成例
export function generateMintlifyDocToken(user, partnerAccount) {
  const payload = {
    // 標準JWTクレーム
    sub: user.id,
    exp: Math.floor(Date.now() / 1000) + 10, // 短い有効期限：10秒以内
    
    // Mintlifyセッション有効期限（8時間）
    expiresAt: Math.floor(Date.now() / 1000) + (60 * 60 * 8),
    
    // MDX条件分岐用ユーザーコンテキスト
    content: {
      userId: user.id,
      email: user.email,
      organization: partnerAccount.name,
      plan: partnerAccount.tier // 例: "enterprise" または "tier-1"
    },
    
    // ページ制御およびナビゲーション制限用グループ
    groups: [partnerAccount.tier, "partner-tier-1"],
    
    // APIプレイグラウンド自動入力用トークン
    apiPlaygroundInputs: {
      header: {
        Authorization: `Bearer ${partnerAccount.ephemeralSandboxKey}`
      }
    }
  };

  return jwt.sign(payload, process.env.MINTLIFY_PRIVATE_SIGNING_KEY, {
    algorithm: "ES256"
  });
}

4. 署名済みJWTをURLフラグメント（Hash）に付与してユーザーをリダイレクトします。

   https://docs.api.example.com/api/v2/private-settlement#eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...
   

   Mintlifyはクライアント側でハッシュ内のトークンを抽出し、事前登録された公開鍵で署名を検証してセッションを確立します。その後、ブラウザのアドレスバーから直ちにハッシュを削除するため、URL履歴やRefererヘッダー経由でのトークン漏洩を防止できます。

ロールベースアクセス制御（RBAC）とページ単位の閲覧制限

認証が確立された後、パートナーの契約プランや権限レベルに応じて閲覧可能なドキュメントを制御します。

1. MDXフロントマターによるページ単位の制御

対象の .mdx ファイル上部で groups を定義します。

---
title: "決済Webhooks仕様書"
description: "基幹決済パートナー向け高スループットAPI"
groups: ["enterprise", "fintech-partners"]
---

セッション内のJWTやSSO属性に指定グループが含まれていない場合、サイドバーナビゲーションから該当ページが自動的に除外され、直接URLにアクセスしてもアクセス拒否（404等）となります。

2. userContext によるページ内コンテンツの動的制御

同一ページ内で一部の記述のみを切り替える場合は、MDX内で userContext を使用します。

# API利用制限とレートリミット

{userContext?.content?.plan === "enterprise" ? (
  <Card title="エンタープライズ専用帯域" icon="shield-check">
    ご契約のアカウントは 10,000 QPS の専有帯域とSLA保証が適用されます。
  </Card>
) : (
  <Card title="標準レートリミット" icon="gauge">
    標準アカウントの制限は 200 QPM です。上限引き上げは担当営業までお問い合わせください。
  </Card>
)}

3. 人間とAIエージェントのコンテンツ分離

MintlifyはAIエージェントやLLM向けにコンテンツをMarkdown形式で自動最適化します。機密性の高い運用ガイドラインなどをAIの学習やスクレイピングから除外したい場合は、<Visibility> コンポーネントを使用します。

<Visibility for="humans">
  <Note>本番用クライアント証明書は90日ごとに管理画面から更新してください。</Note>
</Visibility>

<Visibility for="agents">
  APIリクエストにはAuthorizationヘッダーにBearerトークンを含めてください。
</Visibility>

インタラクティブなAPIプレイグラウンドの安全管理

ブラウザ上から直接APIリクエストを試行できるプレイグラウンド機能は極めて有用ですが、設定を誤ると本番マスターキーの漏洩や意図しないデータ破壊を招く危険性があります。

1. apiPlaygroundInputs による安全なトークン自動入力

開発者に本番キーの手動コピーを求めるのではなく、認証セッションを通じてサンドボックス用の一時トークンを安全に注入します。

{
  "apiPlaygroundInputs": {
    "server": {
      "environment": "sandbox"
    },
    "header": {
      "Authorization": "Bearer sbx_partner_9981aef0"
    },
    "query": {
      "version": "2026-10"
    }
  }
}

これにより、ドキュメントの読み込み時に対応するヘッダーやクエリパラメータが自動入力されます。

2. セキュリティベストプラクティス

• テスト先をサンドボックスに限定： docs.json に設定するOpenAPIサーバーURLは、本番環境ではなく必ず隔離されたサンドボックスやモックサーバーを指定してください。
• 長期間有効なマスターキーを絶対に注入しない： ブラウザに渡すクレデンシャルは、最小権限かつ短時間で無効化されるテスト用トークンに限定してください。
• OpenAPIの x-default でプレースホルダー設定： JWT連携を行わない公開ドキュメントでは、OpenAPIの securitySchemes 内で x-default: "YOUR_SANDBOX_KEY" などのダミー文字列を定義し、実稼働キーをリポジトリに含めないようにしてください。

本番公開前チェックリスト

• ドメイン設定の確認： サブパス（/docs）ではなく、専用サブドメイン（docs.partner.example.com）で公開されているか。
• 認証範囲の選定： 要件に応じて Access 画面で全体認証（Full）または部分認証（Partial）が選択されているか。
• 署名鍵の厳重保管： ES256署名用秘密鍵がコードリポジトリではなくKMS等で安全に管理されているか。
• トークンの有効期限： リプレイ攻撃を防ぐため、JWTの exp が10秒以下に設定されているか。
• グループ権限の設定： 機密APIのMDXファイルに groups 設定が漏れなく施されているか。
• プレイグラウンドの安全確認： テスト先がサンドボックス環境に制限されているか。
• プレビュー環境の保護確認： GitのPRプレビューURLにも認証制限が正常に適用されているか。

これらの手順を遵守することで、エンジニアリングチームはパートナーに高品質な開発者体験を提供しつつ、機密性の高いプライベートAPIをゼロトラストの原則に基づいて堅牢に保護できます。

参考資料

• Authentication setup - Mintlify
• SSO - Mintlify
• Personalized content - Mintlify