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

# 認証

> BeTerKEIBA Core API は Bearer トークンによる API key 認証を採用しています。本ページで認証方式、エラー応答、key 発行・失効のポリシーを説明します。

## 認証方式

BeTerKEIBA Core API は **Bearer 認証 (RFC 6750)** を採用しています。全 endpoint で `Authorization` ヘッダに API key を付与する必要があります。

```http theme={null}
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

* ヘッダ名 `Authorization`、scheme `Bearer` (大文字小文字無視)、scheme と token の間は 1 つ以上の空白文字 (半角スペース / TAB)
* token 部分が空、または API key として認識できない場合は `401 Unauthorized` を返します

### key prefix と mode

API key は Stripe 慣習に従い prefix で **mode** を示します。両 mode とも同じ API URL (`https://api.beter-keiba.com/v1`) で利用できます。

| prefix      | mode | 用途                                            |
| ----------- | ---- | --------------------------------------------- |
| `sk_live_*` | live | 本番運用 (実取引・実課金)                                |
| `sk_test_*` | test | 開発・自動テスト用 (現状は live と同等挙動、将来 sandbox 動作を追加予定) |

prefix は発行時に固定されます。mode を切り替えるにはそれぞれの prefix で新しい key を発行してください。

## エラー応答

<Warning>
  認証失敗時は失敗理由を一切区別せず、常に同一の `401 { error: { code, message } }` を返します。これは「key が存在するか / revoke 済か / 形式不正か」の判別を攻撃者に与えないための仕様です (列挙攻撃の困難化)。

  ```json theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "message": "有効なAPIキーが必要です。"
    }
  }
  ```
</Warning>

具体的に同一 body を返すケース:

| ケース                             | HTTP | body |
| ------------------------------- | ---- | ---- |
| `Authorization` ヘッダ欠落           | 401  | 上記   |
| `Bearer` 以外の scheme (`Basic` 等) | 401  | 上記   |
| token が空 (`Bearer ` のみ)         | 401  | 上記   |
| token が API key として存在しない        | 401  | 上記   |
| token は存在するが revoke 済           | 401  | 上記   |

### 他のエラー応答

エラーレスポンスはすべて `{ error: { code, message } }` 形式に統一されています。

| code           | HTTP | 説明              |
| -------------- | ---- | --------------- |
| `BAD_REQUEST`  | 400  | リクエスト形式不正       |
| `UNAUTHORIZED` | 401  | 認証エラー (上記参照)    |
| `FORBIDDEN`    | 403  | プラン制限などでアクセス権なし |
| `NOT_FOUND`    | 404  | リソース不在          |

## key の発行・失効

key の発行 / 失効はダッシュボード経由で行います (将来公開予定)。本 API には現時点では key 管理用の endpoint はありません。

<Warning>
  発行された key は発行時の 1 度だけ完全な値を確認可能で、以降はサーバー側でも復元できません (SHA-256 hash のみ保存)。紛失した場合は失効 (revoke) して新規発行してください。
</Warning>