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

# Hello Clever API の認証

> すべての Hello Clever API リクエストに app-id と secret-key を含める方法、そして v1 の決済ゲートウェイのリンクに追加のアクセストークンが必要になる場合を解説します。

Hello Clever API への（v1、v2、v3、Card、Cashback の各 API にわたる）すべてのリクエストは、`app-id` と `secret-key` の2つのヘッダーで認証されます。1つのエンドポイント、すなわち v1 のホスト型決済ゲートウェイのリンクについては、同じ認証情報から生成する短命のアクセストークンも追加で必要です。このページでは、認証情報の取得方法と正しい使い方を解説します。

## 始める前に

認証情報を発行するには、有効な Hello Clever の加盟店アカウントが必要です。[連携キー](/ja/integration-keys)のガイドに従って Payments Account を作成し、`app-id` と `secret-key` を取得してください。

## リクエストを認証する

すべてのリクエストで、`app-id` と `secret-key` をヘッダーとして含めてください。

<ParamField header="app-id" type="string" required>
  Hello Clever の Merchant Dashboard から発行されるアプリケーションの識別子です。
</ParamField>

<ParamField header="secret-key" type="string" required>
  `app-id` に紐づくシークレットキーです。クライアントサイドのコードで決して露出させないでください。
</ParamField>

```bash Example request theme={null}
curl --request GET \
  --url https://api.cleverhub.co/api/v2/payins/payin_methods \
  --header 'app-id: YOUR_APP_ID' \
  --header 'secret-key: YOUR_SECRET_KEY'
```

このヘッダーの組み合わせは、[v1](/ja/api/v1/introduction)、[v2](/ja/api/v2/introduction)、[v3](/ja/api/v3/introduction)、[Card](/ja/api/card/overview)、[Cashback](/ja/api/cashback/overview) の各 API のすべてのエンドポイントを認証します。ただし、以下に説明する1つの例外があります。

<Note>
  開発やテストの際は、サンドボックスのベース URL とサンドボックスの認証情報を使ってください。本番稼働の準備が整ってから、本番環境のベース URL と認証情報へ切り替えてください。各 API のバージョンのベース URL は [API の概要](/ja/api/overview#base-urls)を参照してください。
</Note>

## 例外：v1 決済ゲートウェイのリンク用アクセストークン

`POST /v1/payment_gateways/create_payment` でホスト型の決済ゲートウェイのリンクを作成する場合、追加で `access-token` のヘッダーが必要です。`app-id` と `secret-key` のヘッダーを付けてアクセストークンのエンドポイントを呼び出すと生成できます。

<CodeGroup>
  ```bash Request theme={null}
  curl --request GET \
    --url https://api-merchant.helloclever.co/api/v1/payment_gateways/access_token \
    --header 'app-id: YOUR_APP_ID' \
    --header 'secret-key: YOUR_SECRET_KEY'
  ```

  ```json Response theme={null}
  {
    "access_token": "eyJhbGciOi...",
    "expires_in": 3600
  }
  ```
</CodeGroup>

決済ゲートウェイのリンクを作成する際に、返された値を `access-token` のヘッダーで渡してください。

```bash theme={null}
curl --request POST \
  --url https://api-merchant.helloclever.co/api/v1/payment_gateways/create_payment \
  --header 'access-token: eyJhbGciOi...' \
  --header 'Content-Type: application/json' \
  --data '{ ... }'
```

`expires_in` は秒単位です。トークンは 3600 秒（1 時間）有効です。有効期限が切れたら新しいトークンを取得して再試行してください。このトークンが必要なのは決済ゲートウェイのリンクのエンドポイントのみで、その他の v1 のエンドポイントは引き続き `app-id` と `secret-key` のヘッダーを直接使用します。決済ゲートウェイのリンクのエンドポイントの詳細は [v1 API リファレンス](/ja/api/v1/introduction)を参照してください。

## セキュリティのベストプラクティス

<Warning>
  `secret-key` を、クライアントサイドのコード、モバイルアプリ、その他の公開されている場所に埋め込まないでください。常にサーバー側に留めておく必要があります。
</Warning>

* **認証情報は環境変数またはシークレット管理サービスに保管してください。** ソースコードや、バージョン管理にコミットされる設定ファイルには保存しないでください。
* **`secret-key` を定期的にローテーションしてください。** 漏えいが起きた場合の影響範囲を限定できます。
* **すべての API 呼び出しで HTTPS を使ってください。** 認証情報が暗号化された接続で送信されることを確保できます。
* **アクセス範囲を分離してください。** 環境、通貨、アプリケーションごとに個別の Payments Account（したがって個別の認証情報）を作成してください。
* **想定外の利用をモニタリングしてください。** Merchant Dashboard で確認することで、認証情報の悪用を早期に検出できます。
* **`secret-key` を Webhook Secret Key と混同しないでください。** `secret-key` は Hello Clever API へ送る自社からのリクエストを認証するものです。Webhook Secret Key は別の認証情報で、Hello Clever がサーバーへ送る受信 Webhook のペイロードに署名するために使います。検証方法は [Webhook](/ja/api/webhooks) を参照してください。


## Related topics

- [Hello Clever API のセキュリティのベストプラクティス](/ja/security/api-security.md)
- [Hello Clever API の概要](/ja/api/overview.md)
- [Hello Clever の連携キーを安全に取得する](/ja/integration-keys.md)