使用 Vimine 登入

協會的會員使用自己的 Vimine 帳戶登入您的網站，並透過明確的同意，授權您使用他們的部分資料。這就是 OAuth 2.1 加 PKCE：密碼只在 Vimine 的頁面上輸入，絕不會在您的頁面上輸入；您的網站收到的權杖僅限於已授予的權限。

開始之前

您需要一個網站或原生應用用戶端，並已登記您的 redirect_uri——參見登記用戶端——還需要安裝 SDK（安裝 SDK）。如需在不觸及真實資料的情況下開發，請使用測試用戶端和沙箱。

流程

1. 會員點選後，您的網站把瀏覽器（頂層視窗，絕不能是 iframe）送到授權頁面：

   https://app.vimine.network/authorize
       ?client_id=vmc_…&redirect_uri=https://www.example.org/vimine/callback
       &response_type=code&state=…&code_challenge=…&code_challenge_method=S256
       &scope=profile:read%20membership:read

2. 會員登入（如果尚未登入），並看到誰將獲得什麼權限。會員確認或取消。
3. Vimine 把瀏覽器送回您的 redirect_uri，並帶上 code 和 state（或 error=access_denied）。
4. 您的網站在 POST https://api.vimine.network/v1/oauth/token 交換授權碼（grant_type=authorization_code、code、code_verifier、client_id、redirect_uri），獲得一個存取權杖（10 分鐘）和一個重新整理權杖（輪換；30 天，閒置 14 天即失效）。

SDK 會為您完成以上全部步驟。

使用 SDK

任意頁面

import { Vimine } from '@vimine/sdk';

const vimine = new Vimine({
    clientId: 'vmc_…',
    redirectUri: 'https://www.example.org/vimine/callback',
    scopes: ['profile:read', 'membership:read']
});

// 由點選觸發：`returnTo` 是您自己的狀態，回呼之後會原樣交還給您
document.querySelector('#sign-in').addEventListener('click', () => vimine.signIn({ returnTo: location.pathname }));

回呼頁面

const result = await vimine.handleRedirect();   // URL 中沒有登入參數時傳回 null
if (result) location.replace(result.returnTo || '/');

signIn() 的選項：

選項	作用
scopes	本次登入要申請的權限（預設：建構函式中的權限，或 profile:read membership:read）
prompt: 'login'	即使存在有效的 Vimine 工作階段，也強制顯示登入表單
prompt: 'consent'	始終顯示授權同意頁面
returnTo	您自己的狀態（例如會員開始登入時所在的頁面），儲存在本機，由 handleRedirect() 傳回

會員取消時，handleRedirect() 拋出 code 為 access_denied 的 VimineError；當返回與本瀏覽器發起的登入不符時，拋出 state_mismatch 或 no_flow。

工作階段

• 權杖儲存在 sessionStorage 中（每個分頁各自獨立）。storage: 'local' 讓多個分頁共享權杖並同步登出；'memory' 則從不持久儲存。您也可以傳入自己的配接器。
• vimine.getAccessToken() 會在權杖到期前 30 秒自動重新整理；收到 401 的呼叫會在重新整理後重試一次。重複使用的重新整理權杖（例如被複製的權杖）會撤銷整個工作階段系列。
• vimine.onChange(session => …) 會通知登入、重新整理和登出。
• vimine.getSession().sub 是會員在您的協會中的識別碼（vms_…）：長期穩定，在每個協會中都不同，絕不是內部 id。

您可以請求的內容

await vimine.me.get();                                     // profile:read
await vimine.me.update({ phone: '+39 …' });                // profile:write
await vimine.membership.get();                             // membership:read — status, verdict, expires_at, statuto, card
await vimine.membership.events({ limit: 20 });             // 狀態歷史
await vimine.membership.statuto();                         // 現行章程，以及會員是否已接受
await vimine.membership.acceptStatuto({ version: 3 });     // statuto:accept
await vimine.membership.request({ accept_statuto: { version: 3 }, privacy_notice: { version: 2 } });   // membership:request → 待處理的會員卡
await vimine.membership.card();                            // 會員卡權杖（QR Code）及其有效時段
await vimine.legal.acceptances();                          // legal:read → 已接受的內容和尚待確認的內容
await vimine.legal.record({ kind: 'privacy_notice', version: 2 });   // legal:accept → 確認已閱讀協會的隱私權聲明
await vimine.connections.list();  await vimine.connections.revoke('vmc_…');

法律文件

legal.acceptances() 列出此人已接受的文件，並在 pending 下列出現行版本中尚待確認的文件：帳戶使用條款和平臺的隱私權聲明（platform），以及本協會給會員的隱私權聲明（privacy_notice）。請展示文字（GET /v1/legal/{kind}、GET /v1/aps/{slug}/privacy-notice），並用 legal.record() 記錄確認：版本必須是現行版本，否則傳回 422 <kind>_outdated。

生效

一份申請（membership.request()）之後會怎樣，取決於協會如何接納會員——即公開資料中的 admission，詳見入會審核與生效。如果由理事會決定，申請保持 pending，並帶有按順序排列的 pending_reasons（先 approval，再 payment），會費只在獲准入會之後繳納（payment_open）；否則，免費類型的會員資格一建立即為有效，收費類型則在記錄會費後生效。有效的會員資格可能帶有一個未來的 valid_from：從那時起，會員卡在入場時才算數。只要出現 payment，就請向會員展示 quota 和 payment_instructions。

verdict 是入場時真正要看的結果：valid、expired、statuto_required（重新接受章程已逾期）或 inactive。尚未入會的人也可以登入並使用 membership.request：非會員同樣可以同意入會相關的權限；其他權限則要求在該協會持有會員卡。

每個方法的詳細說明見 Vimine；回應結構見型別。

登出

await vimine.signOut();                        // 撤銷 API 工作階段並將其清除
await vimine.signOut({ everywhere: true });    // 同時結束會員的 Vimine 工作階段，然後回到您的網站

使用 everywhere 時，瀏覽器會經過 https://app.vimine.network/oauth/logout?client_id=…&post_logout_redirect_uri=…；返回網址必須位於為該用戶端登記的來源上。當會員登出 Vimine 時，其所有應用的 API 工作階段都會被撤銷（單一登出）；當會員在已連結的應用程式中撤銷某個應用或重設密碼時，也是如此。

不使用 SDK

如果您無法使用 SDK（其他程式語言、低程式碼平臺），該流程就是標準的 OAuth 2.1。

授權——GET https://app.vimine.network/authorize

參數
client_id	您的 vmc_…
redirect_uri	已登記的網址之一，必須完全一致
response_type	code
state	隨機值，返回時用於比對
code_challenge、code_challenge_method	PKCE，僅支援 S256
scope	以空格分隔的權限
prompt	可選：login、consent
ui_locales	可選：Vimine 支援的語言之一——it（預設）、en、zh-Hans、zh-Hant、fr、es、de、pt-BR

交換——POST https://api.vimine.network/v1/oauth/token，請求本文為 application/x-www-form-urlencoded：

grant_type=authorization_code&code=…&code_verifier=…&client_id=vmc_…&redirect_uri=…

回應

{ "access_token": "…", "token_type": "Bearer", "expires_in": 600, "refresh_token": "…",
  "scope": "profile:read membership:read", "sub": "vms_…" }

重新整理——同一端點，使用 grant_type=refresh_token&refresh_token=…&client_id=…：回應中帶有一個新的重新整理權杖（舊權杖為並行請求再保持有效 15 秒，此後再使用它會撤銷整個工作階段系列）。

撤銷——POST /v1/oauth/revoke，參數為 token=…&token_type_hint=refresh_token（RFC 7009）。

發現——GET https://api.vimine.network/.well-known/oauth-authorization-server（RFC 8414）列出端點、scope 和支援的方法。

這些端點的錯誤採用 OAuth 格式：{ "error": "invalid_grant", "error_description": "…" }。