> ## Documentation Index
> Fetch the complete documentation index at: https://docs.magicmealkits.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 인증

> Magic Meal Kits API의 API 키 인증과 라이선스 등급.

## API 키

모든 API 요청은 배포에 설정된 API 키(`MMK_API_KEY`)로 인증합니다. `X-API-KEY` 헤더에
담아 보내세요.

```bash theme={null}
curl -X POST "https://magic-meal-kits-xxxxx.run.app/api/v1/youtube/transcript/v2" \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "format": "json"}'
```

MCP 엔드포인트는 베어러 방식을 선호하는 클라이언트(예: Claude.ai)를 위해
`Authorization: Bearer your-api-key`도 허용합니다. [MCP 개요](/ko/mcp/overview)를
참고하세요.

## API URL과 키는 어디서 얻나요

배포의 **API URL**(Cloud Run 호스트)과 **API 키**는 **Magic Meal Kits 앱의 앱 상태 /
연결 페이지**에 표시됩니다 — 직접 구성하는 값이 아닙니다. 그곳에서 배포를 열고 URL과
키를 복사해 API를 호출하는 모든 곳에 사용하세요.

Make.com 커스텀 앱에서는 연결에 한 번만 등록합니다. **Magic Meal Kits 서비스 URL**과
**API 키**를 입력하면 모든 모듈이 이를 재사용합니다. 커넥션 설정과 관리는
[make.magicmealkits.com/connections](https://make.magicmealkits.com/connections)로
일원화되어 있습니다.

<Note>
  대부분의 제품(Plaud, Tiro, Threads)은 서비스별 자격 증명이 배포의 **서버 측**에
  저장됩니다 — 호출자가 다루는 비밀 값은 MMK API 키뿐입니다. 해당 계정의 연결/재연결은
  (Threads OAuth 계정 포함) 이 엔드포인트가 아니라 Magic Meal Kits 앱에서 진행하세요.
  저장된 토큰이 만료되면 앱에서 다시 연결한 뒤 최신 버전으로 서버를 재배포하세요.

  **Notion은 예외입니다.** 호출자가 요청마다 `X-Notion-Token` 헤더(비공식 작업의 경우
  `X-Notion-Space-ID` / `X-Notion-User-ID` 추가)로 Notion 토큰을 제공합니다.
  [Notion 개요](/api-reference/notion/overview)를 참고하세요.
</Note>

## 라이선스 등급

엔드포인트는 라이선스 등급으로 제한됩니다.

| 등급        | 적용 대상                                 |
| --------- | ------------------------------------- |
| **Basic** | 핵심 유틸리티 엔드포인트 (대부분 라우트의 그룹 단위 기본값)    |
| **Pro**   | Pro 전용 기능 — 라우트별로 추가되며, 최신 엔드포인트의 기본값 |

Basic 키로 Pro 제한 라우트를 호출하면 라이선스 오류가 반환됩니다. 대부분의 Pro
게이트(`license.RequirePro()` — **Plaud**, **Tiro**, 그리고 **Notion**의 Pro 전용 작업)는
\*\*`400`\*\*과 `you are not a magic meal kits PRO user` 메시지로 거부합니다. **YouTube**의
`metadata` Pro 게이트는 예외로, \*\*`403`\*\*과 `Pro account required`를 반환합니다. 그룹별로
보면 YouTube transcript는 Basic(metadata는 Pro), Plaud와 Tiro는 Pro 전용, Notion은
일부 Pro 전용 작업이 있는 Basic입니다.

## 오류 형식

오류 형태는 그룹별로 조금씩 다릅니다 — 각 작업의 응답 스키마를 기준으로 삼으세요.
대부분의 오류는 메시지가 담긴 `error`(또는 `success: false` + `error`) 필드를 가집니다.

| 상태          | 의미                                                                                                 |
| ----------- | -------------------------------------------------------------------------------------------------- |
| `400`       | 잘못된 파라미터/본문, 또는 Basic 키로 호출된 `license.RequirePro()` 라우트 (`you are not a magic meal kits PRO user`) |
| `401`       | API 키 누락/오류, 또는 거부된 서드파티 자격 증명 (계정 재연결)                                                            |
| `402`       | 할당량 소진 (예: Plaud 음성 인식)                                                                            |
| `403`       | YouTube `metadata` Pro 게이트 (`Pro account required`)                                                |
| `404`       | 찾을 수 없음                                                                                            |
| `409`       | 리소스가 아직 준비되지 않음 (예: 자막 생성 중)                                                                       |
| `429`       | 속도 제한                                                                                              |
| `500`–`504` | 업스트림/서버 오류 또는 타임아웃                                                                                 |