> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sorsa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 認証

Sorsa APIはAPIキーでリクエストを認証します。APIキーを持つ人はアカウントと利用枠に全面的にアクセスできるため、パスワードと同じように扱ってください。

***

## 認証の仕組み

Sorsa APIへのすべてのリクエストで、APIキーを `ApiKey` ヘッダーに含める必要があります。HTTPヘッダー名は大文字と小文字を区別しませんが、ここに示す表記を使い、キーの値は一文字も変更せずに指定してください。

```text theme={null}
ApiKey: your_api_key_here
```

ヘッダーがない、名前に誤字がある、またはキーが無効な場合、APIはエラーを返します。下の[トラブルシューティング](#troubleshooting)を参照してください。

**リクエスト例**

```bash theme={null}
curl --request GET \
  --url 'https://api.sorsa.io/v3/info?username=elonmusk' \
  --header 'ApiKey: YOUR_API_KEY'
```

**POSTエンドポイントでは**、`Content-Type` ヘッダーも指定してください。

```bash theme={null}
curl --request POST \
  --url 'https://api.sorsa.io/v3/search-tweets' \
  --header 'ApiKey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"query": "bitcoin", "order": "popular"}'
```

> **ヒント：** [API Playground](https://api.sorsa.io/playground)を使うと、コードを書かずにAPIキーをテストできます。

***

## リクエストの要件

すべてのAPI呼び出しは、次の要件を満たす必要があります。

**HTTPSのみ。** すべてのリクエストで `https://` を使用してください。通常のHTTPリクエストは拒否されます。

**ApiKeyヘッダー。** すべてのリクエストで必須です。OAuth、Bearerトークン、クエリパラメータによる認証は使用しません。

**Content-Typeヘッダー。** POSTリクエストで必須です。`application/json` に設定し、パラメータはJSONボディで渡してください。

**HTTPメソッド。** エンドポイントは操作に応じてGETまたはPOSTを使用します。各エンドポイントのメソッドは、[APIリファレンス](https://docs.sorsa.io/ja/api-reference-guide)に記載されています。

***

## APIキーの管理

**キーの確認。** 有効なAPIキーは[ダッシュボードの概要ページ](https://api.sorsa.io/overview)に表示されます。新規アカウントには100回分の無料リクエストが付与されるため、カードを登録しなくても最初のキーをすぐに利用できます。

**キーの作成と削除。** 新しいキーを発行したり、既存のキーを失効させたりするには、ダッシュボードの[API Keys](https://api.sorsa.io/overview/keys)セクションを開きます。

**使用状況の監視。** [Usage stats](https://api.sorsa.io/overview/usage)ページでリクエスト履歴と残りの利用枠を確認できます。`GET /key-usage-info` エンドポイントを使ってプログラムから取得することも可能です。

> **重要：** キーを削除または置き換えると、古いキーを使っているアプリケーションには直ちに `401 Unauthorized` エラーが返されるようになります。キーを失効させる前に、連携先の設定を更新してください。

***

## セキュリティ上の推奨事項

**クライアント側のコードにキーを公開しないでください。** ブラウザ、モバイルアプリ、その他のフロントエンド環境からSorsa APIを直接呼び出さないでください。APIキーがブラウザの開発者ツール、ネットワークログ、ソースコードから見えてしまいます。必ず自分のバックエンドサーバーを経由してリクエストを送信してください。

**環境変数を使用してください。** キーは `.env` ファイル、または利用するプラットフォームのシークレット管理機能（AWS Secrets Manager、Vercel Environment Variables、Railway Variablesなど）に保存してください。ソースファイルにキーを直接書き込まないでください。

**バージョン管理にキーを含めないでください。** `.env` を `.gitignore` に追加してください。GitHub、GitLab、Bitbucketの公開・非公開リポジトリのいずれにもAPIキーをコミットしないでください。

**漏えいしたキーは直ちに更新してください。** コミット、スクリーンショット、公開フォーラムなどで誤ってキーを公開した場合は、[API Keys](https://api.sorsa.io/overview/keys)セクションで該当のキーを削除し、新しいキーを発行してください。古いキーは即座に使用できなくなります。

***

<a id="troubleshooting" />

## トラブルシューティング

**401 Unauthorized**

`ApiKey` ヘッダーがない、ヘッダー名に誤字がある、キーが削除されている、または元から無効な場合です。ヘッダー名が正しく `ApiKey` になっていることを確認してください。`Api-Key` や `Authorization` ではありません。

**403 Forbidden**

キーは有効ですが、サブスクリプションの期限が切れているか、月間リクエスト枠を使い切っています。[ダッシュボード](https://api.sorsa.io/overview)または `GET /key-usage-info` で残りの利用枠を確認してください。

**429 Too Many Requests**

レート制限（すべてのプランで一律20リクエスト／秒）を超える速度で送信しています。呼び出しの間に短い待機時間を入れ、再試行してください。詳細と再試行の方法は、[レート制限](https://docs.sorsa.io/ja/rate-limits)を参照してください。

**ブラウザでのCORSエラー**

CORS関連のエラーが表示される場合は、フロントエンドのJavaScriptからAPIを呼び出している可能性があります。Sorsa APIはサーバー側での利用専用です。API呼び出しをバックエンドサービスまたはサーバーレス関数に移してください。

***

## 次のステップ

* [レート制限](https://docs.sorsa.io/ja/rate-limits) — リクエストの利用枠と再試行の方法
* [APIキーの使用状況](https://docs.sorsa.io/ja/api-reference/technical-endpoints/api-key-usage) — プログラムから残りの利用枠を確認する方法
* [APIリファレンス](https://docs.sorsa.io/ja/api-reference-guide) — 利用可能なすべてのエンドポイント