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

# 認証

> APIキーの取得方法と認証の仕組み

## APIキーの取得

UTAGE管理画面からAPIキーを発行します。

1. UTAGE管理画面にログイン
2. 右上メニューの **API設定** を開く
3. 「追加する」をクリック
4. 管理名称を入力し、API利用ポリシーに同意して「保存」
5. 表示されたAPIキーをコピーして安全な場所に保存

<Warning>
  APIキーは発行時に一度だけ表示されます。紛失した場合は新しいキーを発行してください。
</Warning>

## 認証方法

全てのAPIリクエストに `Authorization` ヘッダーでAPIキーを送信します。

```bash theme={null}
Authorization: Bearer {api_key}
```

### curlでのテスト

```bash theme={null}
curl -X GET "https://api.utage-system.com/v1/funnels" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

認証に成功するとAPIレスポンスが返ります。失敗した場合は `401 Unauthorized` エラーが返ります。

```json エラーレスポンス例 theme={null}
{
    "error": {
        "code": "unauthorized",
        "message": "APIキーが無効です"
    }
}
```

### リクエストの文字コード

リクエストボディは UTF-8 でエンコードしてください。UTF-8 以外の場合は `400 invalid_encoding` エラーが返ります。

## セキュリティ

* APIキーはハッシュ化して保存されます。平文では保存されません
* 全てのAPIリクエストはログに記録されます
* 不要になったAPIキーは管理画面から無効化してください

## レート制限

APIにはレート制限があります。

| 分間リクエスト数 | 日間リクエスト数  |
| -------- | --------- |
| 60回/分    | 10,000回/日 |

### レスポンスヘッダー

全てのAPIレスポンスに、現在のレート制限状況を示すヘッダーが含まれます。

| ヘッダー                    | 説明                    |
| ----------------------- | --------------------- |
| `X-RateLimit-Limit`     | 分間の最大リクエスト数           |
| `X-RateLimit-Remaining` | 残りのリクエスト数             |
| `X-RateLimit-Reset`     | 制限がリセットされるUNIXタイムスタンプ |

### 制限超過時

レート制限を超過すると `429 Too Many Requests` が返ります。

```json theme={null}
{
    "error": {
        "code": "rate_limit_exceeded",
        "message": "レート制限を超過しました"
    }
}
```

<Tip>
  `X-RateLimit-Reset` ヘッダーの時刻まで待ってからリトライしてください。
</Tip>

### リソース作成上限

レート制限とは別に、データを作成するAPIには作成数の上限があります。超過すると `429` が返ります。

| エラーコード                   | 意味                                         |
| ------------------------ | ------------------------------------------ |
| `monthly_limit_exceeded` | 月間の作成上限を超過（`details.retry_after` に再試行可能日時） |
| `hourly_limit_exceeded`  | 1時間あたりの作成上限を超過                             |
| `total_limit_exceeded`   | 累計の保有上限を超過                                 |

`details.resource_type` に対象のリソース種別が含まれます。

<Note>
  読者作成（`POST /accounts/{account_id}/scenarios/{scenario_id}/readers` および `POST /accounts/{account_id}/line/friends/{friend_id}/readers`）は、短時間に多数登録されるケースに対応するため**分間レート制限の対象外**です。代わりに上記のリソース作成上限（時間・月間）で制御されます。
</Note>

## 認証不要のエンドポイント

以下の参照系エンドポイントは、APIキーなしで利用できます。

| エンドポイント                                | 内容                |
| -------------------------------------- | ----------------- |
| `GET /element-types/funnel`            | ファネルページの要素タイプ一覧   |
| `GET /element-types/funnel/properties` | ファネルページ要素のプロパティ定義 |
| `GET /element-types/mail`              | HTMLメール要素タイプ一覧    |
| `GET /element-types/mail/properties`   | HTMLメール要素のプロパティ定義 |
| `GET /message-types/line`              | LINEメッセージタイプ一覧    |
| `GET /message-condition-types`         | 配信条件タイプ一覧         |