# 認証ガイド

マーケットプレイス版のアクセストークン取得手順を解説します。

## 概要

マーケットプレイス版では、管理コンソールで作成したサービスアカウントの認証情報を使い、Client Credentials フローでアクセストークンを取得します。ユーザーの介在はありません。

|                | マーケットプレイス版         |
| -------------- | ------------------ |
| **認証フロー**      | Client Credentials |
| **用途**         | サーバー間のシステム認証       |
| **トークン取得**     | クライアント認証情報で直接取得    |
| **リフレッシュトークン** | なし（期限切れ後に再取得）      |
| **前提となる画面**    | 管理コンソール            |

詳細仕様は [認証 API リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/basic/api/reference/auth-mp-ref.md) を参照してください。

## 前提条件

- マーケットプレイスで購入した AGENTIC STAR 環境のセットアップが完了していること

- 管理コンソールでサービスアカウントを作成済みであること

- 以下の情報を取得済みであること:

  <!-- -->

  - `Client ID` — サービスアカウントのクライアント ID
  - `Client Secret` — サービスアカウントのシークレット（管理コンソールの詳細画面で確認）
  - `Base URL` — API エンドポイントの外部IP（[アクセス用 IP アドレスの確認](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/basic/build/quickstart/quickstart-azure.md#%E3%82%A2%E3%82%AF%E3%82%BB%E3%82%B9%E7%94%A8-ip-%E3%82%A2%E3%83%89%E3%83%AC%E3%82%B9%E3%81%AE%E7%A2%BA%E8%AA%8D) 参照）

## トークンの取得

サーバー側で以下のリクエストを実行してください。

```bash
curl -X POST https://<auth-domain>/api/v1/auth/external-service-token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "<your-client-id>",
    "client_secret": "<your-client-secret>"
  }'
```

**パラメータ**

- `<auth-domain>`: ご利用環境の認証サービスのドメイン（例: auth.example.com）
- `<your-client-id>`: サービスアカウントのクライアント ID
- `<your-client-secret>`: サービスアカウントのシークレット

**レスポンス例**

```json
{
  "success": true,
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "openid profile email"
}
```

## トークンの再取得

Client Credentials フローではリフレッシュトークンは発行されません。アクセストークンの有効期限（`expires_in` に指定された秒数）が切れた場合は、同じリクエストを再度実行して新しいトークンを取得してください。

> **ベストプラクティス**
>
> 有効期限を管理し、期限切れ前に新しいトークンを取得することで、API 呼び出しの中断を防げます。

## スコープ

マーケットプレイス版ではスコープによる制限はありません。取得したトークン 1 つで、マーケットプレイス版が提供するすべての API を呼び出せます。提供範囲そのものは [システム連携 API リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/basic/api/reference/api-reference.md) を参照してください。

## アクセストークンの利用

取得したアクセストークンは、API リクエストの `Authorization` ヘッダーに Bearer トークンとして設定してください。

```text
Authorization: Bearer <access_token>
```

すべての API エンドポイントで同じ形式を使用します。詳細は [システム連携 API リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/basic/api/reference/api-reference.md) を参照してください。
