身分驗證

Notion OAuth（JWT）

IVGraph 透過 Notion 的 OAuth2 流程驗證使用者身分，不提供使用者名稱與密碼註冊方式。

流程

User clicks "Sign in with Notion"
        |
        v
GET /api/integrations/auth/notion/
        |  -> Redirects to Notion consent screen
        v
User authorizes IVGraph in Notion
        |
        v
Notion redirects to /api/integrations/auth/notion/callback?code=...
        |  -> Backend exchanges code for Notion token
        |  -> Creates/updates Django user
        |  -> Issues JWT tokens
        v
Redirect to dashboard with tokens in URL fragment

JWT 權杖

權杖	有效期間	用途
存取權杖	4 小時	API 身分驗證
更新權杖	7 天	取得新的存取權杖

使用存取權杖：

curl -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." \
  "https://ivgraph.com/api/notion-graph/"

更新已到期的權杖：

curl -X POST "https://ivgraph.com/api/auth/refresh/" \
  -H "Content-Type: application/json" \
  -d '{"refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."}'

回應：

{"access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."}

登出（將更新權杖列入封鎖名單）：

curl -X POST "https://ivgraph.com/api/auth/logout/" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"refresh": "<refresh_token>"}'

身分驗證端點

方法	端點	說明
GET	/api/integrations/auth/notion/	啟動 Notion OAuth 流程
GET	/api/integrations/auth/notion/callback	OAuth 回呼（內部使用）
GET	/api/integrations/auth/notion/status	檢查 OAuth 狀態
POST	/api/auth/refresh/	更新存取權杖
POST	/api/auth/logout/	將更新權杖列入封鎖名單
GET	/api/auth/validate/	檢查權杖是否有效
GET	/api/auth/me/	取得目前使用者資訊

服務權杖（供 LLM 代理程式使用）

服務權杖提供具指定權限範圍的長期存取權，可用於 V1 唯讀 API，專為 LLM 代理程式、自動化指令碼與 CI/CD 管線設計。

權杖格式

• 前綴：ivg_（例如：ivg_a1b2c3d4e5f6...）
• 長度：前綴後接 32 個隨機字元
• 儲存方式：資料庫僅儲存 SHA-256 雜湊值，原始權杖只會在建立時顯示一次

建立權杖

透過 API（需使用 JWT 驗證）：

curl -X POST "https://ivgraph.com/api/tokens/" \
  -H "Authorization: Bearer <jwt_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My LLM Agent",
    "scopes": ["graph:search", "graph:read", "graph:neighbors"],
    "workspace_ids": ["your-workspace-uuid"],
    "expires_in_days": 90
  }'

回應（權杖只會顯示一次！）：

{
  "id": 1,
  "name": "My LLM Agent",
  "token": "ivg_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "prefix": "ivg_a1b2c3",
  "scopes": ["graph:search", "graph:read", "graph:neighbors"],
  "workspace_ids": ["your-workspace-uuid"],
  "is_active": true,
  "created_at": "2026-04-10T12:00:00Z",
  "expires_at": "2026-07-09T12:00:00Z"
}

權限範圍

權限範圍	允許的操作
graph:search	依標題搜尋節點
graph:read	讀取節點詳細資訊與頁面內容
graph:neighbors	取得相鄰節點並走訪路徑

限制

• 每位使用者最多可有 10 個權杖
• 每個權杖至少須有一個權限範圍
• 每個權杖至少須有一個 workspace_id（預設拒絕存取）
• 可選擇設定有效期限（expires_in_days），省略則永不到期

權杖管理

方法	端點	說明
GET	/api/tokens/	列出你的權杖（不含原始值）
POST	/api/tokens/	建立新權杖
DELETE	/api/tokens/<id>/	撤銷權杖（永久生效）