Getting Started

全体的な認証フローの概要

API Key → POST /token → customToken → Firebase REST API → idToken → Bearer トークン

BPIM2 API の認証は 2段階 になっています。アプリの API キーを使って Firebase Custom Token を取得し、それをさらに Firebase の REST API で Firebase ID Token に交換してから、各 API リクエストに Authorization: Bearer <idToken> として付与します。

ステップ 1: API キーを取得する

BPIM2 の Web UI から発行する場合

BPIM2 にログイン（Google / X / LINE のいずれかで認証）

設定画面 → API キー セクションを開く

「キーを発行」ボタンを押す

表示された 64 文字の hex 文字列を安全に保存する（この画面でしか平文表示されません）

API 経由で発行する場合（既に Firebase ID Token がある場合）

レスポンス:

{
  "key": "a1b2c3d4...（64 hex 文字）"
}

⚠️ 発行後は再発行するまで元のキーは確認できません。安全な場所に保存してください。

ステップ 2: Custom Token を取得する

POST /api/v1/token に API キーを付与してリクエストします。

レスポンス:

{
  "customToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600
}

⚠️ この customToken は そのままではベアラートークンとして使用できません。次のステップで Firebase ID Token に交換が必要です。

ステップ 3: Firebase ID Token に交換する

customToken を Firebase Authentication REST API に送信して idToken を取得します。

必要なもの

BPIM2のFirebase Web API Key(固定値です):

AIzaSyAIlzzxI0kZtIe4vvjSIiRwfqSQVZtbluM

リクエスト

レスポンス:

{
  "idToken": "eyJhbGciOiJSUzI1NiIsInR5...",
  "refreshToken": "AMf-vBwA...",
  "expiresIn": "3600",
  "localId": "firebase_uid_xxxx"
}

取得した idToken が最終的に使用する Bearer トークンです。

ステップ 4: API を呼び出す

idToken を Authorization: Bearer ヘッダーに付与してリクエストします。

トークンの有効期限と再取得

Firebase ID Token の有効期限は 1時間 (3600秒) です。期限切れ後は以下のいずれかで再取得します。

方法 A: ステップ 2〜3 を再実行

方法 B: refreshToken を使う

ステップ 3 で取得した refreshToken を使って新しい idToken を取得できます（refreshToken 自体の有効期限は非常に長い）。

レスポンスの id_token フィールドが新しい Bearer トークンです。

エンドポイント別の認証要件まとめ

エンドポイント	認証方式	備考
`POST /token`	`X-Api-Key`	API キー必須、唯一の例外
`GET /me`	Bearer 必須	自分の情報のみ
`GET/PUT /apiKey`	Bearer 必須	自分のキー管理
`GET /usernames/{name}/availability`	Bearer 必須	-
`GET /users/{userId}/profile`	公開: 不要 / 非公開: Bearer	-
`POST/PATCH /users/{userId}/profile`	Bearer 必須（本人のみ）	-
`GET /users/{userId}/scores`	公開: 不要 / 非公開: Bearer	-
`POST /users/{userId}/scores/bulk`	Bearer 必須（本人のみ）	-
`POST /users/{userId}/scores/transfer`	Bearer 必須（本人のみ）	Firestore 移行
`GET /users/{userId}/scores/{songId}/history`	公開: 不要 / 非公開: Bearer	-
`GET /users/{userId}/batches`	公開: 不要 / 非公開: Bearer	認証不要でも取れる
`GET /users/{userId}/batches/{batchId}`	公開: 不要 / 非公開: Bearer	-
`GET /users/{userId}/batches/{date}/scores`	公開: 不要 / 非公開: Bearer	-
`GET /users/{userId}/notifications`	Bearer 必須（本人のみ）	-
`POST /users/{userId}/notifications`	Bearer 必須（本人のみ）	既読更新
`GET /users/{userId}/notifications/count`	Bearer 必須（本人のみ）	-
`GET /users/{userId}/stats/*`	公開: 不要 / 非公開: Bearer	全 stats 系
`GET /users/{userId}/rivals/{rivalId}/scores`	公開: 不要 / 非公開: Bearer	-
`GET /users/{userId}/rivals/following/*`	Bearer 必須	フォロー機能全般
`GET /users/{userId}/rivals/suggestions`	Bearer 必須	viewerId が必須
`GET /users/{userId}/follows`	公開: 不要 / 非公開: Bearer	-
`PUT/DELETE /users/{userId}/follows`	Bearer 必須	フォロー・アンフォロー
`GET /users/{userId}/timeline`	Bearer 必須	viewerId が必須

Python での実装例

よくあるエラーと対処法

ステータス	メッセージ	原因	対処
`401`	`API Key is required`	`X-Api-Key` ヘッダー未指定	ヘッダーを追加
`401`	`Invalid API Key`	API キーが間違いまたは失効	設定画面でキーを再発行
`401`	`Missing or invalid token`	Bearer ヘッダー未指定	`Authorization: Bearer <idToken>` を付与
`401`	`auth/id-token-expired`	ID Token の有効期限切れ	ステップ 2〜3 を再実行してトークンを更新
`403`	`Forbidden: User ID mismatch`	他ユーザーの書き込み系 API を呼び出し	自分の userId のみ使用可能
`403`	`This profile is set as a private.`	非公開ユーザーに未認証でアクセス	認証が必要
`404`	`No importable data found in Firestore.`	Firestore に旧データなし	移行不要（新規ユーザー）

全体的な認証フローの概要#

ステップ 1: API キーを取得する#

BPIM2 の Web UI から発行する場合#

API 経由で発行する場合（既に Firebase ID Token がある場合）#

ステップ 2: Custom Token を取得する#

ステップ 3: Firebase ID Token に交換する#

必要なもの#

リクエスト#

ステップ 4: API を呼び出す#

トークンの有効期限と再取得#

方法 A: ステップ 2〜3 を再実行#

方法 B: refreshToken を使う#

エンドポイント別の認証要件まとめ#

Python での実装例#

よくあるエラーと対処法#

全体的な認証フローの概要

ステップ 1: API キーを取得する

BPIM2 の Web UI から発行する場合

API 経由で発行する場合（既に Firebase ID Token がある場合）

ステップ 2: Custom Token を取得する

ステップ 3: Firebase ID Token に交換する

必要なもの

リクエスト

ステップ 4: API を呼び出す

トークンの有効期限と再取得

方法 A: ステップ 2〜3 を再実行

方法 B: refreshToken を使う

エンドポイント別の認証要件まとめ

Python での実装例

よくあるエラーと対処法