# api-vault — เอกสารฉบับเต็มสำหรับ LLM

> api-vault คือคลัง API ส่วนตัวของเจ้าของคนเดียว: ค้น API สาธารณะเป็นภาษาไทยได้ · เก็บ API key แบบเข้ารหัส (envelope encryption) · ดึง Key ลง .env ด้วยคำสั่ง `vault pull` ที่ต้องอนุมัติด้วย TOTP ทุกครั้ง · ไม่ยิง API แทนผู้ใช้

เว็บ: https://api-vault-two.vercel.app · ซอร์สโค้ด: https://github.com/VoramethP/api-vault
ข้อควรรู้ก่อนช่วยผู้ใช้: api-vault ออก API key เองไม่ได้ (ต้องสมัครที่เว็บเจ้าของ API) · Key ไม่เคยถูกส่งให้ LLM หรือบริการภายนอก ·
อย่าขอให้ผู้ใช้วางค่า Key, token หรือรหัสผ่านในแชต

---

# Runbook — จากเข้าเว็บ ถึงใช้ API ในโค้ด

> สำหรับเจ้าของ เมื่อลืมไปแล้วว่าต้องทำอะไรบ้าง · ไฟล์นี้อยู่ใน repo public — **ห้ามใส่ค่า Key, token หรือรหัสผ่านลงในนี้**

เว็บ: **https://api-vault-two.vercel.app** · เอกสารนี้บนเว็บ: `/docs` (ไอคอนหนังสือบนแถบบน) · ฉบับให้ LLM: `/llms-full.txt`

| ทำเมื่อไหร่ | ขั้นตอน |
|---|---|
| ครั้งเดียว | **1** ล็อกอิน + TOTP |
| ทุก API ใหม่ | **2** ค้นหา API → **3** กด "ขอ Key" สมัครที่เว็บเจ้าของ → **4** เก็บลง Vault |
| ทุกโปรเจกต์ที่จะใช้ | **5** ผูก Key กับโปรเจกต์ → **6** `vault pull` ลง `.env` → **7** ใช้ในโค้ด |

API ที่ไม่ต้องใช้ key (ป้าย "ไม่ต้องใช้ key") ข้ามข้อ 3–6 ได้เลย — เรียก URL ตรง ๆ จากโค้ด

---

## 1. เข้าเว็บ + ล็อกอิน

1. เปิดเว็บ → เด้งไปหน้า **เข้าสู่ระบบ** → ใส่อีเมล + รหัสผ่านของเจ้าของ (ไม่มีปุ่มสมัคร — มีผู้ใช้คนเดียว)
2. หน้า **ยืนยันตัวตน** → ใส่รหัส 6 หลักจากแอป authenticator ในมือถือ
   - ครั้งแรกสุดจะเป็นหน้า **ตั้งค่า TOTP** ให้สแกน QR ก่อน
3. เข้าได้แล้วจะเห็นหน้า **ค้นหา** · เมนูบนสุดมี `ค้นหา` · `Vault`

| เจอปัญหา | ทำยังไง |
|---|---|
| รหัส TOTP ไม่ผ่าน | รอรหัสรอบใหม่แล้วพิมพ์ทันที · เช็กว่าเวลาในมือถือตั้งเป็นอัตโนมัติ |
| มือถือหาย / ลบแอป authenticator ไปแล้ว | Supabase dashboard › Authentication › Users › ผู้ใช้ › ลบ MFA factor → ล็อกอินใหม่จะได้หน้าตั้งค่า TOTP |
| ลืมรหัสผ่าน | Supabase dashboard › Authentication › Users › ผู้ใช้ › ส่งลิงก์รีเซ็ตรหัสผ่าน |

## 2. ค้นหา API

หน้า `/` (เมนู **ค้นหา**)

- พิมพ์ได้ทั้งไทยและอังกฤษ เช่น `อัตราแลกเปลี่ยนแบบไม่ต้องใช้ key`, `พยากรณ์อากาศ`, `cat pictures`
- ตัวกรองด้านซ้าย: หมวด · การยืนยันตัวตน · HTTPS · CORS (เรียกจากเบราว์เซอร์ได้ไหม)
- **"ไม่เจอ API ที่ตรง"** = คำไทยนั้นไม่อยู่ในพจนานุกรม → ลองคำอังกฤษ หรือคำไทยที่ง่ายกว่า
- การ์ดแต่ละใบ: กด **ชื่อ** (มีไอคอน ↗) = เปิดเว็บของ API นั้น · ป้ายบอกว่าต้องใช้ key ไหม มี HTTPS ไหม · API ที่ต้องใช้ key มีปุ่ม **ขอ Key**

### ไม่มีในคลัง → เพิ่มเอง

1. ปุ่ม **เพิ่ม Entry** ข้างช่องค้น
2. กรอกชื่อ · URL · **คำอธิบายเป็นภาษาอังกฤษ** (ถ้าเป็นไทยจะค้นไม่เจอ) · หมวด (เลือกของเดิมหรือพิมพ์ใหม่) · การยืนยันตัวตน
3. บันทึก → กลับไปหน้าค้นพร้อมชื่อนั้น · การ์ดมีป้าย **เพิ่มเอง** และปุ่มแก้/ลบ
   (Entry จากคลังตั้งต้นแก้/ลบไม่ได้ · Entry ที่มี Key ผูกอยู่ลบไม่ได้ ต้องลบ Key ก่อน)

## 3. ขอ Key จากเจ้าของ API + เก็บลง Vault

api-vault **ออก Key เองไม่ได้** — Key ผูกกับบัญชีของคุณที่เจ้าของ API (โควตา, ค่าบริการ) ต้องสมัครที่เว็บเขา
และสมัครแทนอัตโนมัติไม่ได้ (แต่ละเจ้าขั้นตอนต่างกัน มี CAPTCHA / ยืนยันอีเมล)

1. บนการ์ด API กด **ขอ Key** → เกิดสองอย่างพร้อมกัน:
   - แท็บใหม่เปิดเว็บเจ้าของ API
   - หน้า api-vault เปิดฟอร์ม **เพิ่ม Key** ของ API นั้นค้างไว้ พร้อมขั้นตอน
2. ในแท็บเจ้าของ: สมัคร / เข้าสู่ระบบ → หาหน้า API keys (มักอยู่ใน Dashboard, Account, Developer) → สร้าง Key → คัดลอก
   - ลิงก์มักพาไปหน้าเอกสาร ไม่ใช่หน้าสมัคร — หาปุ่ม Sign up / Get API key ในหน้านั้น
   - แท็บไม่เปิด (เบราว์เซอร์บล็อก popup) → กดลิงก์ **แท็บไม่เปิด? เปิดเว็บ …** ในฟอร์ม
3. กลับมาแท็บ api-vault → วางใน **ค่า Key** (ชื่อตั้งให้แล้ว แก้ได้) → **เพิ่ม Key** → แจ้งเตือนมีปุ่ม **ไปผูกโปรเจกต์** (ข้อ 5)
   · อย่าพัก Key ไว้ในโน้ต แชต หรือไฟล์ในโปรเจกต์

## 4. จัดการ Key ใน Vault

มี Key อยู่แล้ว (ไม่ต้องสมัครใหม่): เมนู **Vault** › แท็บ **Key** › **เพิ่ม Key** → ค้นชื่อ API → ใส่ชื่อ + ค่า
Key ถูกเข้ารหัสที่ server ก่อนลงฐานข้อมูล · ในรายการจะเห็นแค่ชื่อ + 4 ตัวท้าย (ถ้า Key ยาว ≥ 16 ตัว)

| อยากทำ | ที่ไหน |
|---|---|
| ดูค่า Key อีกครั้ง | ปุ่ม **Reveal** → ใส่ TOTP ใหม่ (รหัสหนึ่งใช้ได้ครั้งเดียว) |
| เปลี่ยน Key (เจ้าของ API ออกให้ใหม่) | ปุ่มดินสอ → ใส่ค่าใหม่ = หมุน Key · เว้นว่าง = แค่เปลี่ยนชื่อ |
| ดูว่าใครดึง Key ไปเมื่อไหร่ | แท็บ **Audit** |

## 5. สร้างโปรเจกต์ + ผูก Key

**Vault › แท็บ โปรเจกต์**

1. พิมพ์ชื่อโปรเจกต์ (เช่น `weather-bot`) → **สร้างโปรเจกต์** — ชื่อนี้คือที่จะพิมพ์ใน `vault pull <ชื่อ>`
2. ในการ์ดโปรเจกต์: เลือก Key + ใส่**ชื่อตัวแปร** (ระบบเดาให้ เช่น `OPENWEATHER_API_KEY` แก้ได้) → **ผูก**
3. ผูกได้หลาย Key ต่อโปรเจกต์ · Key เดียวผูกได้หลายโปรเจกต์

## 6. ดึง Key ลง `.env` ด้วย `vault` CLI

### 6.1 ครั้งแรกของแต่ละเครื่อง

```bash
# ติดตั้ง (ต้องมี Node ≥ 20) — รันในโฟลเดอร์ repo api-vault
npm i -g ./cli
```

1. เว็บ: **Vault › แท็บ CLI** → ตั้งชื่อเครื่อง (เช่น `macbook-work`) → **สร้าง token** → **คัดลอก** (แสดงครั้งเดียว)
2. terminal:
   ```bash
   vault login
   ```
   วาง token (ไม่แสดงบนจอ) → ได้ `✔ login แล้ว: <ชื่อเครื่อง> · หมดอายุ ...`
3. token อายุ **30 วัน** — หมดแล้วสร้างใหม่แล้ว `vault login` อีกครั้ง · เช็กได้ด้วย `vault whoami`

> token อย่างเดียวดึง Key ไม่ได้ — ทุกครั้งต้องอนุมัติบนเว็บด้วย TOTP

### 6.2 ทุกครั้งที่จะดึง

ในโฟลเดอร์โปรเจกต์ของคุณ:

```bash
# .env ต้องอยู่ใน .gitignore ก่อน ไม่งั้น vault pull จะไม่ยอมเขียน
echo ".env" >> .gitignore
```

```bash
vault pull weather-bot
```

1. terminal แสดง **รหัส** (เช่น `ABCD-2345`) และเปิดหน้า **อนุมัติ vault pull** ในเบราว์เซอร์ให้เอง
2. บนเว็บ: เช็กว่ารหัสตรงกับใน terminal · เช็กชื่อเครื่อง/โปรเจกต์/ตัวแปร → ใส่ TOTP → **อนุมัติ**
3. terminal: `✔ /path/.env · เพิ่ม: OPENWEATHER_API_KEY`

- ดึงซ้ำ = อัปเดตเฉพาะบรรทัดของตัวแปรที่ผูกไว้ บรรทัดอื่นใน `.env` ไม่ถูกแตะ
- ไฟล์อื่น: `vault pull weather-bot --file .env.local`
- คำขอหมดอายุใน 10 นาที · Ctrl+C = ยกเลิกคำขอ

### ไม่มี CLI ในเครื่องนั้น

**Vault › Key › Reveal** → ใส่ TOTP → คัดลอกค่าไปวางใน `.env` เอง

## 7. ใช้ในโค้ด

api-vault **ไม่ได้ยิง API แทนคุณ** — โค้ดของคุณอ่าน Key จาก `.env` แล้วเรียก API ของเจ้าของเองตรง ๆ

```bash
# Node ≥ 20 อ่าน .env ได้เอง
node --env-file=.env app.js
```

```js
const res = await fetch(`https://api.example.com/v1/data?appid=${process.env.OPENWEATHER_API_KEY}`)
```

| สแต็ก | อ่าน `.env` ยังไง |
|---|---|
| Node | `node --env-file=.env` แล้ว `process.env.X` |
| Nuxt / Vite / Next | อ่าน `.env` เองอยู่แล้ว · ใช้ Key **ฝั่ง server เท่านั้น** (อย่าใส่ใน public config) |
| Python | `pip install python-dotenv` → `load_dotenv()` → `os.environ["X"]` |
| Deploy (Vercel ฯลฯ) | ใส่ค่าใน env ของ host จากไฟล์ เช่น `vercel env add X production < file` — ห้ามวางในแชต |

วิธีเรียก (URL, ใส่ Key ใน header หรือ query) ดูจากเอกสารของ API นั้น — กดชื่อบนการ์ดในข้อ 2

---

## CLI ขึ้นข้อความนี้ → ทำยังไง

| ข้อความ | ทำ |
|---|---|
| `ยังไม่ได้ login` | ข้อ 6.1 |
| `.env ไม่อยู่ใน .gitignore` | เพิ่ม `.env` ใน `.gitignore` แล้วรันใหม่ |
| `.env ถูก git track อยู่` | `git rm --cached .env` (ถ้าเคย push ขึ้นไปแล้ว → หมุน Key ทุกตัวในไฟล์นั้น) |
| `โปรเจกต์ ... ยังไม่มี Key` | ข้อ 5 ผูก Key ก่อน |
| `คำขอหมดอายุ` / `หมดเวลารออนุมัติ` | รัน `vault pull` ใหม่ แล้วอนุมัติภายใน 10 นาที |
| token หมดอายุ / ถูกเพิกถอน | สร้าง token ใหม่ที่ Vault › CLI แล้ว `vault login` |
| `ต่อ ... ไม่ได้` | เช็กเน็ต · เปิดเว็บดูว่าขึ้นไหม |

## เรื่องความปลอดภัยที่ต้องจำ

- เครื่องหาย / สงสัยว่า token หลุด → **Vault › CLI › เพิกถอน** token ของเครื่องนั้น
- Key หลุด (ขึ้น git, วางในแชต) → ไปเว็บเจ้าของ API ออก Key ใหม่ → ดินสอในหน้า Key ใส่ค่าใหม่ → `vault pull` ทุกโปรเจกต์ที่ใช้
- `VAULT_MASTER_KEY` (อยู่ใน env ของ Vercel + สำเนานอกเครื่อง) หาย = **Key ทุกตัวใน Vault ถอดกลับไม่ได้**
- ทุก Reveal / Pull ถูกบันทึกใน **Audit** — ดูเป็นระยะว่ามีรายการที่ไม่ได้ทำเองไหม