# Authentication Guide

How to obtain an access token in the Marketplace edition.

## Overview

In the Marketplace edition you obtain an access token with the Client Credentials flow, using the credentials of a service account created in the admin console. No user is involved.

|                         | Marketplace                               |
| ----------------------- | ----------------------------------------- |
| **Authentication Flow** | Client Credentials                        |
| **Use Case**            | Server-to-server system authentication    |
| **Token Retrieval**     | Obtained directly with client credentials |
| **Refresh Token**       | No (re-acquire after expiration)          |
| **Required screen**     | Admin console                             |

For detailed specifications, see the [Authentication API Reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/basic/api/reference/auth-mp-ref.md).

## Prerequisites

- Setup of the AGENTIC STAR environment purchased through Marketplace is complete

- A service account has been created in the admin console

- The following information has been obtained:

  <!-- -->

  - `Client ID` — Service account client ID
  - `Client Secret` — Service account secret (viewable on the detail screen in the admin console)
  - `Base URL` — External IP of the API endpoint (see [Checking Access IP Addresses](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/basic/build/quickstart/quickstart-azure.md#checking-access-ip-addresses))

## Token Retrieval

Execute the following request on the server side.

```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>"
  }'
```

**Parameters**

- `<auth-domain>`: Domain of the authentication service of your environment (e.g., auth.example.com)
- `<your-client-id>`: Service account client ID
- `<your-client-secret>`: Service account secret

**Response Example**

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

## Token Re-acquisition

The Client Credentials flow does not issue refresh tokens. When the access token expires (after the number of seconds specified in `expires_in`), execute the same request again to obtain a new token.

> **Best Practice**
>
> Manage the expiration time and obtain a new token before expiration to prevent interruptions in API calls.

## Scopes

The Marketplace edition applies no scope-based restrictions: a single token can call every API the Marketplace edition provides. For which APIs that is, see the [System Integration API Reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/basic/api/reference/api-reference.md).

## Using Access Tokens

Set the obtained access token as a Bearer token in the `Authorization` header of API requests.

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

The same format is used for all API endpoints. See [System Integration API Reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/basic/api/reference/api-reference.md) for details.
