Mintlify에서 비공개 API 문서를 위한 게이트 액세스 및 사용자 인증 설정 방법

유료 파트너, 엔터프라이즈 고객 또는 특정 에코시스템 연동사를 대상으로 비공개 API 및 SDK 문서를 운영하는 엔지니어링 팀과 플랫폼 아키텍트는 상충하는 두 가지 요구사항을 충족해야 합니다. 개발자에게는 Mintlify의 MDX 및 OpenAPI 기반 인터랙티브 API 레퍼런스와 실시간 테스트용 플레이그라운드(Playground)를 제공해야 하지만, 동시에 핵심 결제 엔드포인트와 내부 관리용 인터페이스는 공용 웹 크롤러와 인가되지 않은 사용자로부터 엄격히 격리해야 합니다.

Mintlify는 이러한 보안 문제를 해결하기 위해 조직 내부 인증, 비밀번호 보호, 엔터프라이즈 싱글 사인온(SSO / OAuth 2.0), 서명된 JWT(JSON Web Token) 인증 등 네 가지 접근 제어 방식을 지원합니다. 이 가이드에서는 도메인 구성 요건, 설정 워크플로, MDX 프론트매터(Frontmatter) 기반의 그룹별 역할 기반 접근 제어(RBAC), 그리고 실사용 환경을 위한 API 플레이그라운드 자격 증명 보안 사전 입력 방식을 단계별로 살펴봅니다.

아키텍처 필수 조건 및 도메인 제약사항

인증 방식을 구성하기 전, 엔지니어링 팀은 Mintlify의 호스팅 제약 조건을 확인해야 합니다.

1. 독립 도메인 호스팅 필수: 전체 인증 및 부분 인증 모두 전용 커스텀 도메인(예: docs.api.example.com) 또는 Mintlify 서브도메인(예: example.mintlify.site)에서 호스팅되어야 합니다. 서브패스 배포(예: example.com/docs)에서는 게이트 인증이 지원되지 않습니다. 서브패스 환경에서는 강제 차단 기능이 없는 개인화(Personalization) 기능만 활용할 수 있습니다.
2. 접근 제어 범위(전체 인증 vs. 부분 인증): 사이트 전체와 OpenAPI 스펙을 로그인 필수로 보호하는 전체 인증(Full Authentication) 또는 기본 시작 가이드는 공개하고 엔터프라이즈 엔드포인트만 차단하는 부분 인증(Partial Authentication) 중 선택할 수 있습니다.
3. 풀 리퀘스트 프리뷰 배포(Preview Deployments) 보안: Git 연동을 통해 PR마다 생성되는 프리뷰 URL은 미공개 API가 외부로 유출되는 취약점이 될 수 있습니다. Mintlify 대시보드에서 인증을 활성화하면 모든 프리뷰 배포에도 동일한 보안 게이트가 자동으로 적용됩니다.

인증 방식 비교 매트릭스

방법 1: 비밀번호 보호 (신속한 임시 게이트)

소수의 전략적 파트너에게 초기 SDK를 전달하거나 NDA 기반의 프리뷰를 제공해야 하는 경우, 별도의 IdP 연동 없이 즉시 접근을 통제할 수 있습니다.

설정 단계

1. Mintlify 대시보드에 로그인한 후 대상 프로젝트의 Access 탭으로 이동합니다.
2. Visibility 설정을 Public에서 Private로 변경합니다.
3. Method 목록에서 Password를 선택합니다.
4. 강력한 공유 비밀번호를 입력하고 Save changes를 클릭합니다.

아키텍처 고려사항

설정에 2분도 채 걸리지 않지만, 모든 사용자가 단일 비밀번호를 공유하므로 개별 사용자 감사 로그를 추적할 수 없고 파트너별 권한 분리가 불가능합니다. 특정 협력사의 접근을 차단하려면 비밀번호를 새로 발급해야 하므로, 장기 프로덕션 환경보다는 프로토타입 단계에 적합합니다.

방법 2: 엔터프라이즈 SSO 및 OAuth 2.0 (계정 연합)

사내 개발자 포털이나 대기업 고객을 위한 전용 파트너 문서의 경우 SAML 2.0 또는 OAuth 2.0을 통해 기업 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. 사용자 속성 문(Attribute Statements) 매핑: Mintlify 표준에 맞춰 속성을 매핑합니다.
   • firstName -> user.firstName
   • lastName -> user.lastName
   • Name -> user.email(Name ID 형식은 EmailAddress로 지정).
4. 메타데이터 URL 등록: Okta에서 발급된 Metadata URL을 복사하여 Mintlify 대시보드의 해당 필드에 입력한 후 Save changes를 클릭합니다.

설정이 완료되면 문서 도메인에 접속하는 모든 사용자는 기업 IdP 인증 페이지로 리다이렉트되며, 인증을 통과한 사용자만 API 스펙을 열람할 수 있습니다.

방법 3: JWT 기반 커스텀 인증 (자체 서비스 무중단 연동)

상용 SaaS 또는 개발자 플랫폼 환경에서 파트너는 이미 여러분의 서비스 콘솔에 로그인되어 있습니다. 문서 확인 시 재로그인을 요구하지 않고 매끄러운 경험을 제공하기 위해 Mintlify는 비대칭 키 기반의 JWT 인증 브리지를 제공합니다.

아키텍처 흐름

사용자 브라우저                 자체 서비스 백엔드 (Backend)         Mintlify 문서 포털
      |                                |                                   |
      | 1. "비공개 API 문서" 클릭        |                                   |
      |------------------------------->|                                   |
      |                                | 2. 권한 정보가 담긴 페이로드 생성 후 |
      |                                |    ES256 비공개키로 JWT 서명      |
      | 3. 문서 URL Hash로 리다이렉트   |                                   |
      |    https://docs.example.com/#JWT|                                  |
      |<-------------------------------|                                   |
      |                                                                    |
      | 4. URL 해시의 JWT를 포함하여 문서 페이지 요청                      |
      |------------------------------------------------------------------->|
      |                                | 5. ES256 서명 검증 및 그룹 적용,  |
      |                                |    브라우저 히스토리에서 해시 제거 |
      | 6. 인가된 비공개 엔드포인트 및 사전 입력된 Playground 렌더링       |
      |<-------------------------------------------------------------------|

구현 단계

1. Mintlify 대시보드의 Access(또는 Personalization) 설정에서 JWT 방식을 선택하고 자체 로그인 엔드포인트 URL을 입력합니다.
2. 대시보드에서 암호화 키 쌍을 생성하고, 발급된 서명용 비공개키를 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 세션 만료 시간
    expiresAt: Math.floor(Date.now() / 1000) + (60 * 60 * 8), // 8시간 로컬 세션
    
    // MDX 조건부 렌더링에 사용할 사용자 컨텍스트
    content: {
      userId: user.id,
      email: user.email,
      organization: partnerAccount.name,
      plan: partnerAccount.tier // 예: "enterprise" 또는 "growth"
    },
    
    // 내비게이션 필터링 및 페이지 차단용 권한 그룹
    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 클라이언트는 해시에서 토큰을 추출하고 사전 등록된 공개키로 서명을 검증한 후 로컬 세션을 수립합니다. 검증 직후 브라우저 히스토리 API를 통해 해시를 즉시 제거하여 토큰이 외부로 유출되는 것을 차단합니다.

역할 기반 접근 제어(RBAC) 및 페이지 단위 격리

인증이 완료된 후, 엔지니어링 팀은 파트너의 등급에 맞춰 열람 가능한 API 문서를 세분화해야 합니다.

1. MDX 프론트매터(Frontmatter) 기반 페이지 격리

비공개 엔드포인트의 .mdx 파일 상단에 허용 그룹을 선언합니다.

---
title: "기업 결제 정산 Webhooks"
description: "고처리량 정산 전용 비공개 웹훅 규격"
groups: ["enterprise", "fintech-partners"]
---

사용자의 JWT 또는 SSO 세션에 해당 그룹이 포함되어 있지 않으면 사이드바 내비게이션에서 링크가 제거되며, URL로 직접 접근하더라도 404 또는 접근 제한 화면이 반환됩니다.

2. MDX 내 userContext를 활용한 조건부 렌더링

공통 안내 문서 내에서 특정 파트너만을 위한 안내 사항을 동적으로 표시할 때는 userContext를 사용합니다.

# API 호출 한도 및 쿼터 정책

{userContext?.content?.plan === "enterprise" ? (
  <Card title="전용 엔터프라이즈 쿼터" icon="shield-check">
    귀사 계정에는 전용 초당 10,000건(QPS) 처리량과 SLA 보장이 적용됩니다.
  </Card>
) : (
  <Card title="기본 호출 한도" icon="gauge">
    표준 개발자 쿼터는 분당 200건입니다. 한도 증액은 영업팀에 문의하세요.
  </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 서버 주소의 기본값을 운영 환경이 아닌 격리된 샌드박스 또는 모의(Mock) 서버로 지정하세요.
• 영구 마스터 키 주입 금지: apiPlaygroundInputs에 전달하는 키는 권한이 제한된 단기 테스트용 토큰이어야 합니다.
• OpenAPI x-default 플레이스홀더 활용: JWT 연동이 없는 공개 페이지에서는 OpenAPI securitySchemes 내에 x-default: "YOUR_SANDBOX_KEY"와 같은 안내 문구를 지정하고 실제 키를 코드베이스에 포함하지 마세요.

프로덕션 배포 체크리스트

• 도메인 호스팅 확인: 게이트 인증이 지원되지 않는 서브패스(/docs) 대신 전용 서브도메인(docs.partner.example.com)으로 설정되었는가?
• 인증 범위 확정: 비즈니스 요구에 따라 Access 메뉴에서 전체 인증(Full) 또는 부분 인증(Partial)을 명확히 설정했는가?
• 서명 키 보관: ES256 서명용 비공개키가 Git이 아닌 KMS나 보안 금고에 안전하게 저장되었는가?
• 토큰 수명 최소화: 재전송 공격 방지를 위해 JWT exp 클레임이 10초 이하로 제한되었는가?
• 권한 그룹 검증: 비공개 API 문서의 MDX 프론트매터에 groups 태그가 누락 없이 적용되었는가?
• 플레이그라운드 격리: 기본 호출 대상이 샌드박스 또는 Mock 서버로 제한되었는가?
• 프리뷰 배포 검증: PR 프리뷰 환경에도 동일한 게이트 인증이 적용되어 있는지 확인했는가?

이러한 체계를 갖추면 엔지니어링 팀은 핵심 파트너에게 뛰어난 대화형 문서 경험을 제공함과 동시에 비공개 API 자산을 제로 트러스트(Zero Trust) 관점에서 빈틈없이 보호할 수 있습니다.

참고 자료

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