Claude CodeユーザーのためのAPI入門2 - APIキーと認証を知って安全にAPIを使おう

はじめに：APIを使うには「許可証」が必要

前回の記事では、APIは「決まった方法でお願いすれば、欲しいデータが返ってくる仕組み」であること、そして郵便番号APIを使って実際にAPIを体験しました。

前回の最後でもお伝えしましたが、無料で使えるAPIは、実はかなり珍しいです。多くのAPIは有料、もしくは一定の利用量を超えると有料になります。
有料ということは、「誰がどれだけ使ったか」を管理する仕組みが必要ですよね。勝手に使い放題では、APIを提供する側が困ってしまいます。

この「管理」に使われるのが、今回紹介する「APIキー」と「アクセストークン」という2つの仕組みです。ものすごく雑に分けると、APIを使う際の認証方式はこの2種類に分かれます。
今回はこの2つの違いを、具体的な例を使いながら解説していきます。

※詳しい方向け：この記事でも前回と同様、「正確性」「完璧に書く」ことよりも、Claude Codeを使い始めた方にAPI認証の概念を伝えることを重視しています。OAuth 2.0のフロー詳細などには踏み込みませんので、ご了承ください。

今回の登場人物とシステム構成

今回の説明は少し複雑なので、まず「登場人物」を整理しておきます。説明用の、架空のWebシステムです。

APIサービスの提供元：Google

Googleが提供するAPIのうち、今回は以下の2つを使います。
・翻訳API ― 文章を翻訳してくれるAPI
・Gmail API ― Gmailの受信メール一覧を取得できるAPI

サービスの提供者：オレオレ株式会社

GoogleのAPIを活用して、「ベンリサービス」というWebサービスを運営している会社です。ベンリサービスには2つの機能があります。
1. 翻訳機能 ― 翻訳したい文章と「原文の言語（例：日本語）」「訳文の言語（例：英語）」を指定して「翻訳」ボタンを押すと、翻訳してくれる
2. メール一覧機能 ― 指定した日付のGmail受信メールを一覧表示してくれる

サービスの利用者：ぼくくん と わたしちゃん

ベンリサービスを使っている一般ユーザーです。

この登場人物を頭に入れた上で、読み進めてください。

1. APIキー：「どのシステムがAPIを使うか」を判別する仕組み

APIキーの取得

まずは翻訳機能に使われる翻訳APIを例に、APIキーの仕組みを見ていきましょう。

オレオレ株式会社がGoogleの翻訳APIを使うためには、最初にGoogleに対して、「オレオレ株式会社の担当者が」「こういうサービスでAPIを使います」と登録する必要があります。
この登録をすると、Googleから「APIキー」と呼ばれる文字列が発行されます。APIキーは、いわば「APIを使うための会員証」のようなものです。

APIキーを使った翻訳の流れ

APIキーが発行されたら、ベンリサービスの翻訳機能が使えるようになります。ぼくくんが翻訳機能を使う時の流れを見てみましょう。

1. ぼくくんがベンリサービスで「Hello」を日本語に翻訳してほしいとリクエスト
2. ベンリサービスが内部で、オレオレ株式会社のAPIキーを使ってGoogleの翻訳APIを実行
3. Googleの翻訳APIが「こんにちは」という結果を返す
4. ベンリサービスがぼくくんの画面に翻訳結果を表示

ここで大事なポイントがあります。ぼくくんとわたしちゃんは、直接Googleに申し込みをしているわけではありません。
APIキーの登録も利用料金の支払いも、すべてサービス提供者であるオレオレ株式会社が行っています。
ぼくくんたちは、ベンリサービスを通じて間接的にGoogleのAPIを使っているだけです。

翻訳APIは「誰がやっても同じ結果」

もうひとつ大事な特徴があります。
翻訳APIは、ぼくくんが「Hello → 日本語」で翻訳しても、わたしちゃんが「Hello → 日本語」で翻訳しても、結果は同じ「こんにちは」です。

つまり翻訳APIでは、「どのシステムがAPIを使っているか」さえ分かれば十分で、「誰が使っているか」を区別する必要がありません。このような形式のAPIでは、APIキーによる認証が使われることが多いです。

2. アクセストークン：「誰がAPIを使うか」を判別する仕組み

Gmailの場合は「誰か」が重要

では、ベンリサービスのもう一つの機能、メール一覧機能はどうでしょうか。

この機能はGmail APIを使って、指定した日付の受信メールを一覧表示するものです。ここで、翻訳APIとは決定的に異なる問題が出てきます。
ぼくくんとわたしちゃんでは、受信メールの内容がまったく違います。当たり前ですよね。ぼくくんのメールボックスにはぼくくん宛のメールが、わたしちゃんのメールボックスにはわたしちゃん宛のメールが入っています。

つまり、「どのシステムがAPIを使っているか」だけでなく、「誰がそのAPIを実行しているか」という情報も必要になります。
この「誰が」を判別するために必要なのが、アクセストークンです。

「Googleでログイン」の裏側

突然ですが、なにかWebサービスを使うときに、こんな画面を見たことはありませんか？

特定のサービスで「Googleでログイン」というボタンをクリックすると、Googleのログイン画面が開き、「このアプリケーションがGmailの読み取りを許可しますか？」のような確認画面が表示される ―― あの画面、見覚えがある方も多いのではないでしょうか。
実はあの画面は、内部でアクセストークンを取得している仕組みなのです。
流れはこうです。

1. ぼくくんがベンリサービスの「メール一覧」機能を使おうとする
2. 「Googleでログイン」ボタンが表示される
3. ぼくくんがGoogleにログインし、「Gmailの読み取りを許可しますか？」に「許可する」をクリック
4. Googleがぼくくん用のアクセストークンを発行する
5. ベンリサービスがそのアクセストークンを使って、ぼくくんのGmail受信メールを取得
6. ぼくくんの画面にメール一覧が表示される

アクセストークンはユーザーごとに発行されます。 ぼくくん用のアクセストークンと、わたしちゃん用のアクセストークンはまったくの別物です。
このアクセストークンを使うことで、「誰がそのAPIを実行しているか」を判別できるわけです。
また、アクセストークンにも「どのシステムでAPIを実行しているか」の情報が含まれており、サービス提供者の利用量管理・課金にも使われます。

もうひとつ大事な特徴として、アクセストークンにはとても短い有効期限があります。だいたい数十分〜数時間程度で無効になり、期限が切れたら再度ログイン・許可が必要です。（この特徴が、後で説明するセキュリティ対策に深く関わってきます）

ここまでのまとめ

ここまでの内容を整理しておきましょう。
・APIキー ― 「どのシステムがAPIを使うか」を判別する仕組み。誰が実行しても同じ結果になるAPI（例：翻訳API）で多く使われる
・アクセストークン ― 「誰がAPIを使うか」を判別する仕組み。ユーザーによって結果が異なるAPI（例：Gmail API）で多く使われる
・どちらのケースでも、利用料金の支払いはサービス提供者（オレオレ株式会社）がAPI提供者（Google）に行う。ユーザー（ぼくくん・わたしちゃん）がGoogleに直接課金されることはない

キーやトークンが流出したらどうなるの？

ここからはちょっと怖い話です。でも、とても大切な話なので、ぜひ読んでいってください。

APIキーが流出した場合

オレオレ株式会社のAPIキーが、まったく関係のない「ワルワル株式会社」に渡ってしまったらどうなるでしょうか。

ワルワル株式会社は、盗んだAPIキーを使って、Googleの翻訳APIを「オレオレ株式会社のシステムとして」実行できてしまいます。
APIキーで利用状況を計算しているので、ワルワル株式会社が悪意を持って大量にAPIを実行した分も、すべて「オレオレ株式会社のAPI利用」として計算されます。
つまり、オレオレ株式会社は、まったく関係のないワルワル株式会社の利用料金まで払わされることになるのです！

アクセストークンが流出した場合

では、ぼくくんのアクセストークンが、ワルワル株式会社の「ハッカーさん」に渡ってしまったらどうなるでしょうか。

ハッカーさんは、Gmail取得のAPIを「オレオレ株式会社の」サービスから「ぼくくんとして」実行することができてしまいます。
これは2つの大きな問題を引き起こします。

1. 利用料金がオレオレ株式会社にかかる（APIキー流出と同じ問題）
2. ぼくくんのGmail受信メールが、ハッカーさんの手に渡ってしまう

特に2つ目は極めて深刻です。メールには個人情報や機密情報が含まれている可能性があり、情報漏洩という大事件に発展します。
どちらのケースでも、キーやトークンの流出は非常に大きな問題につながります。

じゃあどうする？ 流出への対策

APIキーの対策

APIキーの流出対策として、APIサービスの提供元（この例ではGoogle）では、以下のような設定が用意されています。

1. 利用上限の設定 ― 一定の利用料金を超えた場合に、APIの実行を停止したり、管理者に通知するよう設定できる
2. IPアドレス制限 ― 指定のIPアドレス（オレオレ株式会社のサーバー）からしかAPIを実行できないようにする

どちらの対策も考え方は同じです。「万が一キーが流出しても、被害が出ないようにする、もしくは最小限に抑える」という方針です。

アクセストークンの対策

アクセストークンについては、実は「有効期限がとても短いこと」自体が、大きな対策になっています。
先ほど、アクセストークンは数十分〜数時間で無効になるとお伝えしました。つまり、もし流出しても、短時間で自動的に使えなくなるのです。

APIキーは一度発行されると基本的にずっと有効です（だからこそ利用上限やIPアドレス制限のような対策が重要になります）。一方、アクセストークンは何もしなくても勝手に無効になります。
もちろん、流出しないに越したことはありません。しかし万が一流出した場合でも、被害が起きる時間が限定される仕組みになっているのです。これは、アクセストークンの大きな利点と言えます。
（とはいえ、その短期間で流出する可能性も勿論あるので、流出しにくい作りにするのはとても大切ですね）

Claude Codeを使う時のAPIキー管理の注意点

ここまで読んで、「APIキーやアクセストークンが大事なものだと分かった。でも、実際にClaude Codeで開発するときは、どう気をつければいいの？」と思った方もいるでしょう。

ここまでの説明では「オレオレ株式会社（サービス提供者）」と「ぼくくん（利用者）」を分けて説明してきました。でも、Claude Codeで自分専用のアプリを作る場合、あなたが「サービス提供者」と「利用者」の両方になります。
APIキーの取得も、利用料金の支払いも、すべて自分自身で行います。だからこそ、APIキーの管理は他人事ではないのです。

Claude Codeで開発を進めていると、APIキーを扱う場面が出てきます。たとえば翻訳APIや天気予報APIなど、外部のAPIを使ったアプリを作るときです。

ここで絶対に覚えておいてほしいのが、APIキーの正しい管理方法です。

やってはいけないこと：

・APIキーをプログラムのコードに直接書き込む
・APIキーが書かれたファイルを、GitHubなどにそのまま公開する
もしAPIキーが書かれたコードをGitHubに公開してしまうと、世界中の誰でもそのキーを見ることができてしまいます。先ほどの「ワルワル株式会社」の例と同じ状況になりかねません。
仮にプライベートリポジトリでも、このキーを書いたままGitHubに入れてしまうのは、非常に危険な行為なので、絶対に避けるべきです。

正しい管理方法：

・APIキーは「.env（ドットイーエヌブイ）ファイル」という専用の設定ファイルに保存する
・プログラムからは .env ファイルを読み込んでAPIキーを使う
・.env ファイルはGitに含めないように設定する（`.gitignore`に追加する）
・Claude Codeの設定で、「.envファイルを読み込まない」という設定を追加する。これにより、Claude Codeが誤って.envファイルの中身を読み取ってしまうリスクを防げます。詳しい設定方法はこちらの記事で解説されています(こちら外部サイトなので、そのうち自分でノウハウ図書館に書くかも・・・。)

難しく感じるかもしれませんが、Claude Codeに「APIキーは.envファイルで管理してください」とお願いすれば、適切に設定してくれます。大事なのは、「APIキーは大切なものだから、コードに直接書かないで」と意識することです。

まとめ

今回の内容を振り返りましょう。
・APIを使う際の認証方式には、主に「APIキー」と「アクセストークン」の2種類がある
・APIキーは「どのシステムがAPIを使うか」を判別する仕組み。誰が実行しても同じ結果になるAPIで多く使われる
・アクセストークンは「誰がAPIを使うか」を判別する仕組み。ユーザーごとに結果が異なるAPIで多く使われる
・どちらの場合も、流出すると大きな問題につながる。ただし、それぞれ対策の仕組みがある
・Claude Codeで開発する際は、APIキーは .env ファイルで管理し、コードに直接書かないことが大切

前回の「APIとは何か」に続いて、今回は「APIの認証」について解説しました。「APIキーとアクセストークン、なんとなく分かった！」と思っていただけたら嬉しいです。
APIの世界はまだまだ奥が深いですが、一歩ずつ理解していけば怖くありません。1度で理解することは難しいかもしれませんが、少しずつ進めていきましょう！

Claude Code慣れてきた人向けシリーズ

・Claude Codeユーザーのための GitHub入門 ― 「コードの管理」ってなぜ必要なの？
・Claude Codeユーザーのための GitHub入門2 ― 「ブランチ」を理解して便利に開発！
・Claude Codeユーザーのための API入門 ― APIを知ればシステムの世界が大きく広がる！
・Claude CodeユーザーのためのAPI入門2 - APIキーと認証を知って安全にAPIを使おう
・Claude Codeに慣れてきた方へ！Dockerを覚えて爆速で環境構築できるようになろう！