Supabase Key 형식

# Supabase 키 형식 · 환경 변수 매핑

**프로젝트**: saas-engine  
**목적**: 대시보드에서 보이는 **Legacy JWT** vs **Publishable / Secret (`sb_*`)** 을 같은 앱 슬롯에 어떻게 넣는지 정리합니다.  
**실제 키 값**은 Git에 넣지 마세요. 로컬 백업이 필요하면 `docs/supabase-dashboard-keys.local.md` 를 쓰고(파일은 `.gitignore` 처리됨), 내용은 `.env.local` 과 맞춥니다.

---

## 매핑 표

| 대시보드 / 유형 | `.env.local` 변수 |
|-----------------|-------------------|
| Legacy **anon** `public` (JWT `eyJ…`) | `NEXT_PUBLIC_SUPABASE_ANON_KEY` |
| **Publishable** (`sb_publishable_…`) | `NEXT_PUBLIC_SUPABASE_ANON_KEY` 또는 `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` |
| Legacy **service_role** (JWT `eyJ…`) | `SUPABASE_SERVICE_ROLE_KEY` |
| **Secret** (`sb_secret_…`) | `SUPABASE_SERVICE_ROLE_KEY` |

공통 URL: `NEXT_PUBLIC_SUPABASE_URL`

클라이언트 초기화는 `engine/auth/supabase-public-config.ts` — anon 자리에 JWT와 Publishable 중 하나만 있으면 됩니다.

로컬에 **JWT와 sb_* 를 함께** 보관하려면: `NEXT_PUBLIC_SUPABASE_ANON_KEY` + `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY`, `SUPABASE_SERVICE_ROLE_KEY` + 백업용 `SUPABASE_SB_SECRET_KEY`(앱 코드 미사용, 수동 교체·기록용) 패턴을 쓸 수 있습니다.

---

## 검증

- `pnpm check-env` — anon 자리는 `NEXT_PUBLIC_SUPABASE_ANON_KEY` **또는** `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` 중 하나만 있어도 통과합니다 (`scripts/check-env.mjs`).
- `/api/health` — 동일 기준으로 `auth.ready` 판단 (`app/api/health/route.ts`).

---

## 참고

- 운영 순서: `docs/operational-order.md`
- Polar 연동 플랜: `docs/plan-polar-integration.md`

<h1>Supabase 키 형식 · 환경 변수 매핑</h1>
<p><strong>프로젝트</strong>: saas-engine<br><strong>목적</strong>: 대시보드에서 보이는 <strong>Legacy JWT</strong> vs <strong>Publishable / Secret (<code>sb_*</code>)</strong> 을 같은 앱 슬롯에 어떻게 넣는지 정리합니다.<br><strong>실제 키 값</strong>은 Git에 넣지 마세요. 로컬 백업이 필요하면 <code>docs/supabase-dashboard-keys.local.md</code> 를 쓰고(파일은 <code>.gitignore</code> 처리됨), 내용은 <code>.env.local</code> 과 맞춥니다.</p>
<hr>
<h2>매핑 표</h2>
<table>
<thead>
<tr>
<th>대시보드 / 유형</th>
<th><code>.env.local</code> 변수</th>
</tr>
</thead>
<tbody><tr>
<td>Legacy <strong>anon</strong> <code>public</code> (JWT <code>eyJ…</code>)</td>
<td><code>NEXT_PUBLIC_SUPABASE_ANON_KEY</code></td>
</tr>
<tr>
<td><strong>Publishable</strong> (<code>sb_publishable_…</code>)</td>
<td><code>NEXT_PUBLIC_SUPABASE_ANON_KEY</code> 또는 <code>NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY</code></td>
</tr>
<tr>
<td>Legacy <strong>service_role</strong> (JWT <code>eyJ…</code>)</td>
<td><code>SUPABASE_SERVICE_ROLE_KEY</code></td>
</tr>
<tr>
<td><strong>Secret</strong> (<code>sb_secret_…</code>)</td>
<td><code>SUPABASE_SERVICE_ROLE_KEY</code></td>
</tr>
</tbody></table>
<p>공통 URL: <code>NEXT_PUBLIC_SUPABASE_URL</code></p>
<p>클라이언트 초기화는 <code>engine/auth/supabase-public-config.ts</code> — anon 자리에 JWT와 Publishable 중 하나만 있으면 됩니다.</p>
<p>로컬에 <em><em>JWT와 sb_</em> 를 함께</em>* 보관하려면: <code>NEXT_PUBLIC_SUPABASE_ANON_KEY</code> + <code>NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY</code>, <code>SUPABASE_SERVICE_ROLE_KEY</code> + 백업용 <code>SUPABASE_SB_SECRET_KEY</code>(앱 코드 미사용, 수동 교체·기록용) 패턴을 쓸 수 있습니다.</p>
<hr>
<h2>검증</h2>
<ul>
<li><code>pnpm check-env</code> — anon 자리는 <code>NEXT_PUBLIC_SUPABASE_ANON_KEY</code> <strong>또는</strong> <code>NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY</code> 중 하나만 있어도 통과합니다 (<code>scripts/check-env.mjs</code>).</li>
<li><code>/api/health</code> — 동일 기준으로 <code>auth.ready</code> 판단 (<code>app/api/health/route.ts</code>).</li>
</ul>
<hr>
<h2>참고</h2>
<ul>
<li>운영 순서: <code>docs/operational-order.md</code></li>
<li>Polar 연동 플랜: <code>docs/plan-polar-integration.md</code></li>
</ul>