# Authentication Guide

This guide explains how to obtain access tokens in the Marketplace edition.

## Overview

Use one of two authentication flows depending on the purpose.

|                         | Application                                                        | System Integration                                      |
| ----------------------- | ------------------------------------------------------------------ | ------------------------------------------------------- |
| **Authentication flow** | Authorization Code (PKCE)                                          | Client Credentials                                      |
| **Purpose**             | Employees sign in with their own accounts from external tools      | Your company's systems use it server to server          |
| **Token retrieval**     | Sign in with a browser and obtain it through an authorization code | Obtain it directly with the service account credentials |
| **Refresh token**       | Yes                                                                | No (obtain a new one after expiry)                      |
| **Where to prepare**    | Authorization server console                                       | Admin console                                           |

For the preparation steps, see the [API Setup Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/setup-guide.md). For the detailed specification, see the [Authentication API Reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/auth-mp-ref.md).

## Prerequisites

- The setup of the AGENTIC STAR environment purchased on the marketplace is complete
- Application: an administrator has opened the entrance for sign-in from an external tool and created an external tool client in the authorization server console ([API Setup Guide — Creating an Application](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/setup-guide.md#external-tool-client))
- System integration: a service account has been created in the admin console, and you have its `Client ID` and `Client Secret` ([API Setup Guide — Creating a System Integration](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/setup-guide.md#service-account))

Tokens and APIs are on different domains. Tokens are on the domain of the authentication service (or the external entrance of the authorization server), and APIs are on the domain of the external API. Both were decided by the administrator when building the environment.

## Authorization Code Flow

An employee signs in with an external tool and obtains an access token and a refresh token through an authorization code. MCP-capable AI clients (such as Claude Code and Codex) perform these steps by themselves ([AI Client Connection Guide (MCP)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/ai-client-guide.md)). To sign in from your own application, follow the steps below.

### 1. Authorization Request

Redirect the user in the browser to the authorization endpoint of the external entrance of the authorization server. PKCE (S256) is required.

```text
GET https://<authorization-server-domain>/realms/<realm>/protocol/openid-connect/auth?
  response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=http://localhost:8765/callback
  &scope=openid
  &state=STATE_VALUE
  &code_challenge=CODE_CHALLENGE
  &code_challenge_method=S256
```

| Parameter               | Required    | Description                                                                                             |
| ----------------------- | ----------- | ------------------------------------------------------------------------------------------------------- |
| `response_type`         | Required    | Fixed to `code`                                                                                         |
| `client_id`             | Required    | The ID of the client created in the authorization server console                                        |
| `redirect_uri`          | Required    | A redirect URI registered for the client                                                                |
| `scope`                 | Required    | Include `openid`                                                                                        |
| `state`                 | Recommended | A random value against CSRF. Always check that the returned value is the same as the one in the request |
| `code_challenge`        | Required    | The SHA-256 of `code_verifier`, base64url-encoded                                                       |
| `code_challenge_method` | Required    | Fixed to `S256`                                                                                         |

### 2. User Authentication

On the sign-in screen of the authorization server, sign in with the same email address and password as for the Main Screen. Only approved users who have verified their email address can sign in (when the client was created by following the API Setup Guide).

### 3. Receive the Authorization Code

After sign-in, the browser is redirected to `redirect_uri`. The URL contains a temporary authorization code (`code`).

### 4. Exchange the Code for Tokens

Exchange the authorization code for an access token at the token endpoint. The client is public, so do not send `client_secret`.

```bash
curl -X POST https://<authorization-server-domain>/realms/<realm>/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=http://localhost:8765/callback" \
  -d "code_verifier=CODE_VERIFIER"
```

Use `access_token` in the response to call the API, and `refresh_token` to get a new one later.

### 5. Refresh the Token

When the access token expires, get a new one with the refresh token.

```bash
curl -X POST https://<authorization-server-domain>/realms/<realm>/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "refresh_token=REFRESH_TOKEN"
```

## Client Credentials Flow

Obtain an access token with the credentials of a service account created in the admin console. No user interaction is involved. Run the following request on the server side.

```bash
curl -X POST https://<auth-domain>/api/v1/oauth/token \
  -u "<your-client-id>:<your-client-secret>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials"
```

- Send the client authentication either with Basic authentication in the `Authorization` header or with `client_id` and `client_secret` in the body, not both
- `<auth-domain>` is the domain of the authentication service of your environment (for example, `auth.example.com`)

**Response example**

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

Wrong credentials return `401 Unauthorized` (`{"error": "invalid_client", ...}`).

> **The earlier token endpoint**
>
> The earlier `POST https://<auth-domain>/api/v1/auth/external-service-token` (with `client_id` and `client_secret` in a JSON body) can still be used. Its response has `success`, `access_token`, `token_type`, `expires_in`, and `scope`.

### Token Re-acquisition

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

> **Best Practice**
>
> Track the expiration and obtain a new token before it expires to avoid interruptions in API calls.

## Scopes

The Marketplace edition applies no scope restrictions. Neither flow narrows the APIs by scope.

- With an application token, the user can do what the user is permitted to do. What can be done with projects depends on how the user participates in each project and on the organization operations role ([User API Reference (Projects)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/user-api-reference-projects.md))
- The APIs that can be called with a system integration token are those in the [System Integration API Reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/api-reference.md)

## Using Access Tokens

Set the access token you obtained 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. The API address is `https://<your-domain>/api` (`<your-domain>` is the domain of the external API).
