認証

Manabu2 API の呼び出しには、利用者の代わりに動く OAuth 2.0 のアクセストークンか、組織として動く API キーのどちらかを使います。Manabu2 は自前の認可サーバーを持っており、Microsoft Entra ID などの外部 ID プロバイダーとの連携は現在ありません。

1. どちらを使うか

アクセストークン（OAuth） API キー
誰として動くかサインインした利用者組織そのもの（個人に紐付かない）
できることアプリに許可したスコープ ∩ 要求したスコープ ∩ 利用者本人の権限キーに設定したスコープそのもの
向いている用途モバイルアプリ、社内ポータルの画面、MCP 対応の AI アシスタント夜間バッチ、人事システムとの連携、BI への取り込み
有効期限アクセストークンは expires_in 秒（現在 24 時間）。リフレッシュで更新取り消すまで有効（有効期限の設定も可能）

アプリの登録と API キーの発行は、Manabu2 の開発者メニューで行います。開発者または組織管理者の権限が必要です。

2. Manabu2 アカウントでサインインさせる（認可コード + PKCE）

利用者はパスワードを Manabu2 の画面で入力するので、アプリはパスワードを受け取りません。PKCE（S256）は必須です。

① PKCE のペアと state を作る
code_verifier  = base64url(32–64 random bytes)
code_challenge = base64url(sha256(code_verifier))
state          = base64url(16 random bytes)
② サインイン画面に送る
GET https://manabu2.com/connect/authorize
  ?client_id={client_id}
  &redirect_uri={registered redirect URI}
  &response_type=code
  &scope=read%3Acatalog%20read%3Acontent%20read%3Aprogress%20write%3Aprogress
  &state={state}
  &code_challenge={code_challenge}
  &code_challenge_method=S256

redirect_uri は登録したものと完全に一致する必要があります。モバイルではアプリ内 WebView ではなく、OS のブラウザ（ASWebAuthenticationSession / Chrome Custom Tabs）で開いてください。戻ってきたら、state が送った値と一致することを必ず確認します。

③ 認可コードをトークンに交換する
POST https://api.manabu2.com/api/v1/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code={code}
&client_id={client_id}
&redirect_uri={same redirect URI}
&code_verifier={code_verifier}

JSON の本文でも送れます。機密クライアントは client_secret も送ります。認可コードの有効期限は 60 秒で、使えるのは 1 回だけです。レスポンスには access_token・token_type・expires_in・refresh_token・scope が含まれます。

④ API を呼ぶ
GET https://api.manabu2.com/api/v1/courses
Authorization: Bearer {access_token}

3. トークンの更新

POST https://api.manabu2.com/api/v1/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token={refresh_token}
  • 更新のたびに新しいリフレッシュトークンが返り、古いものは使えなくなります。返ってきた新しい値を必ず保存してください。
  • 古いリフレッシュトークンをもう一度送るとエラーになります（セッション自体は有効なままです）。更新処理は複数スレッドから同時に呼ばないでください。
  • アクセストークンの有効期間は expires_in で返ります。値を決め打ちせず、レスポンスの値を使ってください。リフレッシュトークンは 30 日間有効です。

4. API キー

API キーは、利用者を介さないサーバー間連携のための資格情報です。次のどちらかの形で送ります。

X-Api-Key: mnb_live_...

Authorization: Bearer mnb_live_...
  • キーは発行直後に一度だけ表示されます。保存されるのはハッシュだけなので、後から取り出すことはできません。
  • キーは設定したスコープをそのまま持ち、利用者の権限で絞られません。管理者向けスコープを含むキーを発行できるのは組織管理者だけです。
  • モバイルアプリやブラウザで動く JavaScript には、API キーを埋め込まないでください。利用者の端末で動くものは OAuth を使います。

5. パスワードでのサインイン（POST /api/v1/auth/login）

メールアドレスとパスワードでトークンを得るエンドポイントは、Manabu2 自身のアプリ向けです。サードパーティのアプリの client_id では拒否されます。ご自身のアプリでは、上の認可コード + PKCE を使ってください。

6. よくあるエラー

  • redirect_uri が一致しない — 末尾のスラッシュ、http と https、ポート番号の違いでも拒否されます。② と ③ で同じ文字列を送ってください。
  • code_challenge がない、または method が S256 でない — PKCE（S256）は必須です。
  • invalid_grant — 認可コードの期限切れ（60 秒）、使用済み、または code_verifier の不一致です。① からやり直してください。
  • 401 — トークンやキーがない、期限切れ、取り消し済み、またはアカウントが無効になっています。
  • 403 — 認証はできていますが、必要なスコープがないか、その組織・データへの権限がありません。
  • 429 — 呼び出し回数の上限を超えました。Retry-After ヘッダーの秒数だけ待ってから再試行してください。

次： REST API ドキュメント →