API認証ガイド

レシートローラー API は OAuth 2.0 の認可コードフローで認証します。開発者がアプリを登録し、ビジネスアカウントのオーナーが同意画面で許可すると、アプリは認可コードをアクセストークンに交換して API を呼び出せます。この記事では、認可URLのパラメーター、同意画面の動き、トークンの交換・取り消し、返るエラー、使えるスコープをまとめます。最初の1回を手を動かして試したい場合ははじめてのAPI呼び出しから始めてください。

全体の流れ

• 開発者アプリを登録し、クライアントIDとクライアントシークレットを受け取る
• ユーザーのブラウザを https://receiptroller.io/oauth/authorize に送る
• ユーザーが同意画面で「許可する」を押すと、登録済みのリダイレクトURIに code と state が付いて戻る
• サーバーから POST https://receiptroller.io/api/v1/auth/token で code をアクセストークンとリフレッシュトークンに交換する
• Authorization: Bearer {アクセストークン} を付けて API を呼ぶ
• 期限が近づいたらリフレッシュトークンで更新する

アプリを登録する

アプリの登録はビジネスアカウントのオーナーが行います。ビジネスアカウントのプランがスタータープラン以上である必要があります。手順と入力項目はアプリを新規作成するをご覧ください。登録できるリダイレクトURIは1アプリにつき1つです。

認可画面へ送る

GET https://receiptroller.io/oauth/authorize
    ?response_type=code
    &client_id=YOUR_CLIENT_ID
    &redirect_uri=https%3A%2F%2Fexample.com%2Fcallback
    &scope=store.products.read%20store.orders.read
    &state=RANDOM_STATE
    &code_challenge=CODE_CHALLENGE
    &code_challenge_method=S256

未ログインのユーザーは、まずレシートローラーのログイン画面に送られ、ログイン後に同意画面へ戻ります。

同意画面とビジネスアカウントの選択

同意画面の動きは、アプリの「認可時に1つのビジネスアカウントへトークンを紐付ける」の設定で変わります。

• オン（既定）: 同意画面でビジネスアカウントを1つ選びます。選べるのは、ログイン中のユーザーがオーナーであるビジネスアカウントだけです。発行されるトークンはそのビジネスアカウントに紐付き、ユーザー個人は含まれません。そのため /api/v1/me と /api/v1/me/organizations は 403 を返します。API 呼び出しで organizationId は省略でき、別のビジネスアカウントを指定すると 403 になります。
• オフ: ビジネスアカウントは選びません。トークンはユーザー本人のもので、API を呼ぶたびに organizationId を付けます。サーバーは呼び出しごとに、そのユーザーがビジネスアカウントのメンバーかを確認します。複数のビジネスアカウントを切り替えるモバイルアプリ向けです（ネイティブモバイルアプリ向けガイド）。

同意画面では要求されたスコープがチェック済みで並び、ユーザーは外すこともできます。プランがスタータープラン未満のビジネスアカウントは、プランの変更が必要と表示され、そのビジネスアカウントでは許可できません。同じアプリ・同じスコープに一度同意済みの場合、同意画面を出さずにすぐリダイレクトします。

コールバックを受け取る

許可されると、登録したリダイレクトURIに戻ります。

https://example.com/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE

拒否された場合や、ユーザーがすべてのスコープを外した場合は次のように戻ります。

https://example.com/callback?error=access_denied&state=RANDOM_STATE
https://example.com/callback?error=access_denied&error_description=no_scopes_approved&state=RANDOM_STATE

認可コードの有効期限は10分で、一度しか使えません。state は送った値と一致するか必ず確認してください。

認可画面で返るエラー

次のエラーはリダイレクトせず、ブラウザに HTTP 400 の JSON（error、一部は error_description）を表示します。

認可コードをトークンに交換する

サーバー側から送ります。本文は application/x-www-form-urlencoded を推奨します（JSON も受け付けます）。

POST https://receiptroller.io/api/v1/auth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTHORIZATION_CODE
&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&code_verifier=CODE_VERIFIER

• redirect_uri は認可リクエストと同じ値にします。
• client_secret は本文に入れます。Authorization ヘッダーの Basic 認証は読み取りません。公開クライアントは client_secret を送りません。
• 認可リクエストで code_challenge を送った場合は code_verifier が必須です。公開クライアントは PKCE なしで発行されたコードを交換できません。

成功すると 200 が返ります。

{
  "access_token": "…",
  "refresh_token": "…",
  "token_type": "Bearer",
  "expires_in": 28800,
  "scope": "store.products.read store.orders.read",
  "accessToken": "…",
  "refreshToken": "…",
  "tokenType": "Bearer",
  "expiresIn": 28800
}

accessToken などの camelCase のキーは、古いクライアント向けに同じ値を重ねて返しているものです。新しく作るアプリは snake_case のキーを読んでください。scope には実際に許可されたスコープが入るので、要求したものと比べてください。有効期限と更新はアクセストークンの取得と更新で説明します。

トークンエンドポイントのエラー

invalid_grant も 401 で返ります。原因は error_description で確認できます。切り分け方はトークンが取得できない（認証エラー）をご覧ください。

API を呼び出す

GET https://receiptroller.io/api/v1/products
Authorization: Bearer ACCESS_TOKEN

紐付けオフのアプリは ?organizationId= を付けます。トークンがない・無効・期限切れのときは 401、必要なスコープがないときは 403 が返ります。

トークンの状態を確かめる

POST https://receiptroller.io/api/v1/auth/verify
Content-Type: application/json

{ "accessToken": "ACCESS_TOKEN" }

有効なら 200 で active、clientId、scope、expiresAt、organizationId（紐付けオフのトークンは null）が返ります。無効なら 401 です。

トークンを取り消す

POST https://receiptroller.io/api/v1/auth/revoke
Content-Type: application/json

{ "token": "ACCESS_OR_REFRESH_TOKEN", "clientId": "YOUR_CLIENT_ID" }

アクセストークンとリフレッシュトークンのどちらを渡しても、その組がまとめて無効になります。成功すると 200 で {"revoked": true}、該当するトークンがないか別のアプリのトークンなら 400 で {"error": "invalid_token"} が返ります。ビジネスアカウントのオーナーは、ビジネスアカウント詳細のメニューにある「連携アプリ」からアプリの連携を取り消せます。取り消すと、そのビジネスアカウントに対するアプリのトークンはすべて無効になります。

スコープ

アプリに登録したスコープの中から、認可リクエストで必要なものを要求します。user.* のスコープはアプリの審査が必要です（User系スコープの審査申請）。

各スコープの内容はOAuthスコープ一覧と利用可否をご覧ください。

セキュリティのポイント

• client_secret はサーバー側だけで保管します。モバイルアプリなど配布するアプリは「公開クライアント」にして、シークレットの代わりに PKCE を使ってください。
• state はリクエストごとに生成し、コールバックで一致を確認してください。
• PKCE は S256 を使ってください。
• アクセストークンをログや URL に含めないでください。
• アプリが実際に使うスコープだけを要求してください。

関連ガイド

• はじめてのAPI呼び出し
• アプリを新規作成する
• アクセストークンの取得と更新
• リダイレクトURLの設定
• トークンが取得できない（認証エラー）
• MCPでAIエージェントをレシートローラーに接続する