OAuthを使用してアプリをNotiondeskに接続します。

OAuth を使用すると、他の Notiondesk の顧客は、API キーを共有することなく、アプリをワークスペースに接続できます。顧客は Notiondesk にサインインし、アプリが要求する内容を確認して承認します。アプリは Notiondesk REST API のアクセス トークンを受け取り、顧客はいつでもそれを取り消すことができます。この記事では、アプリの登録、PKCE を使用した OAuth 2.0 認証コード フローの実行、トークンの更新、およびエラー処理について説明します。

APIキーの代わりにOAuthを使用するタイミング

すべての Notiondesk API ルートは、両方の認証情報を受け入れ、同じ方法で応答します。つまり、同じスコープ、応答、およびエラーです。

アプリが知っておくべきこと

エンドポイントはハードコーディングするのではなく、認証サーバーのメタデータ文書から読み取ってください。

OAuthクライアントはサーバー上で実行してください。ブラウザベースのクライアントはサポートされていません。トークンの交換、トークンの発行、およびすべてのAPI呼び出しはバックエンドで行ってください。

ステップ1：アプリを登録する

動的クライアント登録で一度登録してください。

201 Created レスポンスには、お客様の client_id と、お客様が client_secret_post を要求したため client_secret が含まれています。このシークレットは一度だけ表示されますので、他のサーバーシークレットと一緒に保管してください。

"token_endpoint_auth_method": "none" を使用すると、アプリは秘密情報を持たない公開クライアントとなり、PKCE がコード交換を保護します。

登録する代わりに、クライアントメタデータドキュメントのHTTPS URLをclient_idとして使用できます。Notiondeskは、顧客がアプリを承認したときにドキュメントを取得し、最大5分間キャッシュします。

リダイレクトURIルール

curl -X POST "https://api.notiondesk.so/oauth/register" \
  -H "Content-Type: application/json" \
  -d '{"client_name": "Acme Reports", "redirect_uris": ["https://acme.example/oauth/callback"], "token_endpoint_auth_method": "client_secret_post"}'

• ループバックホストでは、https または http を使用してください。127.0.0.1、localhost、または [::1]。

• ループバックリダイレクトはどのポートでも一致します。その他のリダイレクトは完全に一致する必要があります。

• ワイルドカード、フラグメント、ホスト名の前に付く認証情報（user@）、バックスラッシュ、非ASCII文字、パーセントエンコードされたホスト名は拒否されます。

• 顧客が同意画面で目にするホストは、リダイレクトURIまたはclient_id URLから取得されます。所有するホストのみを登録してください。

ステップ2：顧客をNotiondeskに誘導する

ランダムなcode_verifierを作成し、次に検証者のSHA-256ハッシュをbase64url（ PKCE ）でエンコードしてcode_challengeを導出します。顧客のブラウザを次のURLにリダイレクトします。

https://api.notiondesk.so/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Facme.example%2Foauth%2Fcallback
  &scope=read%20write
  &state=RANDOM_STATE
  &code_challenge=YOUR_CODE_CHALLENGE
  &code_challenge_method=S256
  &resource=https%3A%2F%2Fapi.notiondesk.so

• resource は必須項目であり、https://api.notiondesk.so と完全に一致する必要があります。小文字で、末尾のスラッシュやパスは含めないでください。値が欠落している場合、または異なる値の場合は invalid_request となります。

• scope はスペース区切りのリストです。アプリで使用するスコープのみを要求してください。

• state はクロスサイトリクエストフォージェリ攻撃から保護します。顧客が再来店した際に確認してください。

Notiondesk REST API 用に発行されたトークンは、REST API でのみ有効です。Workspace MCP 用に発行されたトークンは REST API で拒否され、その逆も同様です。

ステップ3：顧客がアプリを承認する

Notiondesk は同意画面を表示します。顧客はサインインし、アプリ名とホスト、ワークスペース、および顧客の役割で許可されているリクエストのスコープを確認します。顧客はリクエスト全体を承認または拒否します。

アプリが取得できるスコープは、顧客のワークスペースロールによって異なります。

admin を使用すると、アプリでヘルプセンターのブランディングを変更したり、公開ヘルプセンターでスクリプトが読み込まれる統合を設定したり、リダイレクトを削除したりできます。アプリがこれらのルートを使用する場合にのみ、この権限を要求してください。

顧客がリクエストを承認できないのは、以下の場合です。

• 彼らの役割には、あなたが要求した範囲はどれも含まれていません。

• 彼らのワークスペースにはAPIアクセス権限がありません。同意画面には「ワークスペースプランにはAPIアクセス権限が含まれていません」と表示されます。APIアクセスにはエンタープライズプランが必要です。

承認後、ブラウザはcode、state、およびNotiondesk認証サーバーの識別子であるissとともに、お客様のredirect_uriに戻ります。お客様が拒否した場合、リダイレクトには代わりにerror=access_deniedが含まれます。

ステップ4：コードをトークンと交換する

このコードは60秒間有効で、一度だけ使用できます。

パブリッククライアントの場合は、client_secret を削除してください。応答は次のとおりです。

scope には、顧客が付与したスコープが一覧表示されます。これは、あなたが要求したスコープよりも少ない場合があります。両方のトークンをサーバーに保存してください。

ステップ5：Notiondesk APIを呼び出す

アクセストークンをAPIキーと全く同じようにベアラートークンとして送信します。

トークンのスコープは、承認した顧客の現在の役割に限定されます。ビューアーに変更された顧客は、read のみを持ってアプリを離れ、不足しているスコープが必要なルートは 403 insufficient_scope を返します。

レート制限予算とIdempotency-Key値は、グラントに属します。承認ごとに新しいグラントが作成され、それぞれ独自の予算とキーが設定されます。トークンの更新によって、これらの両方が保持されます。

ステップ6：アクセストークンを更新する

アクセストークンの有効期限は1時間です。有効期限が切れる前に、リフレッシュトークンを新しいトークンと交換してください。

更新するたびに、30日間有効な新しい更新トークンが返され、送信したトークンは無効になります。新しいアクセストークンを使用する前に、新しい更新トークンを保存してください。

curl -X POST "https://api.notiondesk.so/oauth/token" \
  -d grant_type=authorization_code \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d code=THE_CODE \
  -d code_verifier=YOUR_CODE_VERIFIER \
  -d redirect_uri=https://acme.example/oauth/callback

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "8f3c...",
  "scope": "read write"
}

curl "https://api.notiondesk.so/sites" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "nd-version: 2026-10-16"

curl -X POST "https://api.notiondesk.so/oauth/token" \
  -d grant_type=refresh_token \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d refresh_token=THE_REFRESH_TOKEN

リフレッシュトークンは絶対に再利用しないでください。既に使用されたトークンを送信すると、トークンがコピーされたことになるため、アクセストークンを含むすべての権限が失効します。その場合、顧客はアプリを再度承認する必要があります。

顧客がアプリの利用を取り消す方法

ワークスペースの所有者と管理者は、「設定」>「開発者」>「接続済みアプリ」で、ワークスペースにアクセスできるすべてのアプリを確認できます。REST API を使用するアプリは、「アクセス」列にREST APIが表示され、アプリ名、承認者、スコープ、最終アクティビティが表示されます。 「取り消し」を実行すると、許可は即座に終了し、アクセス トークンとリフレッシュ トークンは次のリクエストで機能しなくなります。

助成金は自動的に終了することもあります。

• 更新せずに30日経過後。

• リフレッシュトークンが再利用された場合。

承認する顧客にルートに必要な役割が付与されていない場合、またはワークスペースプランにAPIアクセス権限が付与されていない場合、リクエストは拒否されます。権限付与期間が終了する前に役割またはプランが回復すれば、リクエストは再び有効になります。

Notiondesk OAuth のトラブルシューティング

認証エンドポイントとトークンエンドポイントは、Notiondesk APIエラーエンベロープではなく、標準的なOAuthエラーに応答します。

{"error": "invalid_grant", "error_description": "Invalid authorization code."}

認証エンドポイントはこれらのエラーを自身で表示し、無効なリクエストをredirect_uriにリダイレクトすることはありません。同意拒否は、error=access_deniedへのリダイレクトとしてのみアプリに届きます。

API自体への呼び出しは、Notiondesk APIエラーエンベロープで応答します。有効期限切れまたは失効したアクセストークンは、使用できないAPIキーの場合と同じメッセージ「無効または不足しているAPIキー」とともに401 authentication_errorで応答します。

よくある質問

次は？

• Notiondesk REST API を使い始めましょう

• APIキーを使用してNotiondesk APIで認証します。

• Workspace MCPへのアクセスを切断または取り消す