認證

群組GM API 使用 Bearer Token 進行認證。

認證方式

在每個 API 請求的 Header 中加入：

Authorization: Bearer YOUR_API_KEY

範例

curl -X GET https://api.gm.kamigo.tw/api/me \
  -H "Authorization: Bearer gm_xxxxxxxxxxxx"

fetch('https://api.gm.kamigo.tw/api/me', {
  headers: {
    'Authorization': 'Bearer gm_xxxxxxxxxxxx'
  }
})

requests.get(
    'https://api.gm.kamigo.tw/api/me',
    headers={'Authorization': 'Bearer gm_xxxxxxxxxxxx'}
)

API 金鑰格式

gm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

前綴：gm_
長度：36 字元（含前綴）
字元：小寫英文與數字

權限範圍

每把 API 金鑰可設定不同的權限：

權限	說明
`read:messages`	讀取群組訊息
`read:members`	讀取成員資訊
`read:media`	讀取媒體檔案
`write:assistant`	修改自動回覆設定

權限檢查

API 會根據金鑰權限決定可存取的資源：

GET /api/channels/C123/backup/messages

需要 read:messages 權限，否則回傳：

{
  "error": "Insufficient permissions"
}

安全建議

不要在前端曝露金鑰

// ❌ 錯誤：金鑰會被看到
const API_KEY = 'gm_xxxxxxxxxxxx';
fetch('/api/me', { headers: { Authorization: `Bearer ${API_KEY}` }});

// ✅ 正確：透過你的後端代理
fetch('/your-backend/api/me');

使用環境變數

GROUPGM_API_KEY=gm_xxxxxxxxxxxx

const apiKey = process.env.GROUPGM_API_KEY;

# Python
import os
api_key = os.environ.get('GROUPGM_API_KEY')

限制金鑰權限

只授予必要的權限：

只讀取訊息 → read:messages
管理設定  → write:assistant

定期輪換

建議每 90 天更換金鑰。

錯誤處理

401 Unauthorized

金鑰無效或缺失：

{
  "error": "Invalid or missing API key"
}

處理方式：

確認金鑰正確
確認 Header 格式正確
確認金鑰未被刪除

403 Forbidden

權限不足：

{
  "error": "Insufficient permissions"
}

處理方式：

確認金鑰有需要的權限
確認你是該群組的成員
某些功能需要特定方案

OAuth 登入（Web 應用）

如果你開發的是 Web 應用，可以使用 OAuth 流程讓使用者登入：

GET /auth/login

重新導向至 LINE Login，完成後回到你的應用。