OAuth認証

OAuth認証とは

OAuth認証は、外部のアプリケーションにパスワードを渡さずに、NotePM のデータへのアクセスを許可する仕組みです。

NotePM にクライアント（外部アプリ）を登録すると、そのアプリは利用者本人の許可を得たうえで、許可された範囲（スコープ）だけ NotePM API を利用できるようになります。

• アクセスできる範囲は、許可した利用者本人の閲覧権限と、管理者が設定したスコープの両方に従います。

操作できる権限

設定画面（セキュリティ設定）は管理者以上で開けますが、変更できるのはオーナーのみです。

設定前の確認事項

連携するアプリケーション側で決まっているリダイレクトURIを、あらかじめ確認しておいてください。
登録したURI以外には認可コードが返されません。

NotePM側の設定方法

クライアントを登録する

1. 管理者メニューの［セキュリティ設定］をクリックします。
2. 「OAuth認証」のパネルまでスクロールします。
3. ［クライアントを追加］をクリックします。
   
4. 以下を入力します。

5. ［更新する］をクリックします。
6. 保存するとクライアントIDが発行されます。コピーして、連携するアプリケーション側に設定します。
   

スコープ一覧

認可リクエスト

本フローはPKCE（RFC 7636）が必須です。認可リクエストの前に code_verifier（43〜128文字のランダム文字列）を生成し、そのSHA-256ハッシュをBase64URLエンコードした値を code_challenge として送信する必要があります。

ユーザーにNotePMへのアクセス権限を許可させるため、以下のURLへリダイレクトしてください。

GET https://{チームドメイン}.notepm.jp/oauth/authorize HTTP/1.1

Request

リクエスト例

https://{チームドメイン}.notepm.jp/oauth/authorize?response_type=code&client_id={クライアントID}&redirect_uri={リダイレクトURI}&scope=page:read+page:write&code_challenge={コードチャレンジ}&code_challenge_method=S256&state={state}&resource={MCPリソース}

Response

認可リクエストから表示される連携確認画面で、許可ボタンをクリックします。

ユーザーがアクセスを許可すると、指定したリダイレクトURIに認可コードが付与されてリダイレクトされます。

https://{リダイレクトURI}?code={認可コード}&state={state}

https://{リダイレクトURI}?error=access_denied

アクセストークンリクエスト

取得した認可コードをアクセストークンに交換します。

POST https://{チームドメイン}.notepm.jp/oauth/token HTTP/1.1

Request

cURLでのリクエスト例

curl -X POST 'https://{チームドメイン}.notepm.jp/oauth/token' \
-H 'Content-Type: application/json' \
-d '{
    "grant_type": "authorization_code",
    "code": "{認可コード}",
    "redirect_uri": "{リダイレクトURI}",
    "client_id": "{クライアントID}",
    "code_verifier": "{コードベリファイア}"
}'

Response

HTTP/1.1 200 OK
{
    "token_type": "Bearer",
    "expires_in": 86400,
    "access_token": "{アクセストークン}",
    "refresh_token": "{リフレッシュトークン}"
}

APIアクセス

取得したアクセストークンを Authorization リクエストヘッダに付与して、NotePM APIにアクセスします。

Authorization: Bearer {アクセストークン}

cURLでのリクエスト例

curl 'https://{チームドメイン}.notepm.jp/api/v1/pages' \
-H 'Authorization: Bearer {アクセストークン}'

注意: 管理者がNotePM APIを無効にしている場合、OAuth認証を行っていてもAPIは利用できません。

NotePM APIの詳細については、APIドキュメントをご覧ください。

アクセストークンの更新

アクセストークンの有効期限が切れた場合、リフレッシュトークンを使用して新しいアクセストークンを取得できます。

POST https://{チームドメイン}.notepm.jp/oauth/token HTTP/1.1

Request

cURLでのリクエスト例

curl -X POST 'https://{チームドメイン}.notepm.jp/oauth/token' \
-H 'Content-Type: application/json' \
-d '{
    "grant_type": "refresh_token",
    "refresh_token": "{リフレッシュトークン}",
    "client_id": "{クライアントID}"
}'

Response

HTTP/1.1 200 OK
{
    "token_type": "Bearer",
    "expires_in": 86400,
    "access_token": "{新しいアクセストークン}",
    "refresh_token": "{新しいリフレッシュトークン}"
}

アクセストークンの失効

アクセストークンおよびリフレッシュトークンを失効させます。ユーザーがアプリとの連携を解除する際などに使用します。

POST https://{チームドメイン}.notepm.jp/api/oauth/token/revoke HTTP/1.1

Request

リクエストボディは不要です。失効させたいアクセストークンを Authorization ヘッダに付与してリクエストしてください。

cURLでのリクエスト例

curl -X POST 'https://{チームドメイン}.notepm.jp/api/oauth/token/revoke' \
-H 'Authorization: Bearer {アクセストークン}'

Response

HTTP/1.1 204 No Content

接続を解除する

1. 管理者メニューの［セキュリティ設定］＞「OAuth認証」で、対象のクライアントの［接続を解除］をクリックします。
2. 確認画面で［接続を解除］をクリックします。

• 現在接続している利用者は、再度の認可が必要になります。
• クライアント定義（クライアントID・スコープ・リダイレクトURI）は残るため、同じクライアントIDのまま接続を再開できます。

よくある質問

Q. APIアクセストークン（APIキー）との違いは何ですか？

APIアクセストークンは、発行した利用者の権限で動作する固定のトークンです。OAuth認証は、利用者ごとに許可を得たうえで、スコープで範囲を絞ってアクセスさせる仕組みです。

Q. 連携したアプリから、自分が見られないノートの内容を読み取れてしまいますか？

いいえ。許可した利用者本人の閲覧権限に従います。

Q. クライアントシークレットはどこで確認できますか？

NotePM ではクライアントシークレットを発行していません。PKCE（S256）に対応したアプリケーションからご利用ください。

Q. 設定を変更・解除できるのは誰ですか？

オーナーのみです。管理者は設定内容の閲覧のみ可能です。

Q. APIを呼び出せる回数に制限はありますか？

あります。1ユーザーあたり1分間に120回までです。上限を超えた場合は、しばらく時間をおいてからお試しください。

Q. 退職などでユーザーを削除した場合、そのユーザーのトークンはどうなりますか？

使用できなくなります。削除後は、そのトークンでのAPI呼び出しは認証エラーになります。

Q. 利用者ごとに接続を解除できますか？

いいえ。解除はクライアント単位です。［接続を解除］を実行すると、そのクライアントに接続している全員が再度の認可を求められます。