Authentication Guide

This guide explains how to obtain access tokens using AGENTIC STAR authentication flows (OIDC-compliant).

Overview

AGENTIC STAR provides OIDC (OpenID Connect) standard-compliant authentication. Choose the appropriate authentication flow based on your edition.

	SaaS — Application	SaaS — System Integration	Marketplace
Authentication Flow	Authorization Code	Client Credentials	Client Credentials
Use Case	Users log in via browser	Server-to-server system integration (Management API, etc.)	Server-to-server system authentication
Token Retrieval	Obtained via authorization code	Obtained directly with client credentials	Obtained directly with client credentials
Refresh Token	Yes	No (re-acquire after expiration)	No (re-acquire after expiration)
Required Admin Panel	Console	Console	Admin

For detailed specifications, see the authentication API reference for each edition.

SaaS: Authentication API Reference (SaaS)
Marketplace: Authentication API Reference (MP)

Authorization Code Flow (SaaS)

This is the authentication flow where users log in via a browser and obtain access tokens and refresh tokens through an authorization screen.

Prerequisites

An application (client) is already registered in Console (Console Guide)
client_id and client_secret have been obtained
A redirect URI (redirect_uri) has been registered

1. Authorization Request

Redirect the user to the authorization endpoint in a browser.

GET https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/authorize?
  response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &state=STATE_VALUE

Parameters

Parameter	Required	Description
`response_type`	Required	Fixed as `code`
`client_id`	Required	Client ID obtained from Console
`redirect_uri`	Required	Redirect URI registered in Console
`state`	Recommended	Random value for CSRF attack prevention. If specified, it is returned in the response, so always verify that the returned value matches the value sent in the request
`nonce`	—	Random value for ID Token replay attack prevention (recommended). If specified, the same value is inserted into the `nonce` claim of the ID Token, so verify that they match
`ui_locales`	—	Display language for login and consent screens. Supports `ja` (default), `en`, `fr`, `es`, `th`, `id`, `ar`

2. User Authentication

When you access the authorization endpoint, the login screen is displayed. Log in using the same authentication method as your usual account.

If the consent screen is enabled for the application, it will appear on first use or when scopes are added. Review the content and grant permission.

Once authentication is complete, an authorization code is issued and returned to the redirect URI.

Eligible Accounts

An account for your contracted AGENTIC STAR environment is required to log in.

Application Publication Status

Who can access the application depends on its publication status (Published / Unpublished). See Console Guide — Publication Settings for details.

3. Receive Authorization Code

When the user grants authorization, the browser redirects to redirect_uri. The URL contains a temporary authorization code (code).

https://yourapp.com/callback?
  code=AUTH_CODE_VALUE
  &state=STATE_VALUE

warning

If state is specified, always verify that the returned value matches the value from the request (CSRF prevention)
The code has a short expiration time, so exchange it for a token in the next step immediately

4. Obtain Token

Exchange the authorization code for an access token. Execute the following request on the server side.

curl
curl -X POST https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE_VALUE" \
  -d "redirect_uri=https://yourapp.com/callback" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Parameters

grant_type: Fixed as authorization_code
code: Authorization code obtained in step 3
redirect_uri: Same URI as in step 1
client_id: Client ID obtained from Console
client_secret: Client secret obtained from Console (keep it secure)

Response Example

JSON
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_expires_in": 86400,
  "scope": "openid chat:exec chat:history chat:file mcp:all"
}

Token Refresh

You can obtain a new access token using the refresh token (refresh_token) obtained from the Authorization Code flow.

curl
curl -X POST https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=REFRESH_TOKEN_VALUE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Response Example

JSON
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_expires_in": 86400,
  "scope": "openid chat:exec chat:history chat:file mcp:all"
}

Best Practice

It is recommended to refresh the token just before the access token expires (e.g., within the last 5 minutes). This prevents token expiration errors during API calls.

In the Authorization Code flow, when the consent screen is enabled in Console application settings, a consent screen is displayed for users to grant access permissions to the application.

Application name, logo, and description
List of access permissions requested by the application
Support URL, Privacy Policy URL, Terms of Use URL

About Access Permissions

Access permissions define the range of operations the application can perform via the API. The list of permissions is displayed based on the scopes assigned to the application in Console. Access to basic user information (profile, email address) is permitted by default as OIDC standard scopes.

These settings are managed in Console application configuration. See Console Guide for details.

First use — Displayed when a user uses the application for the first time. Once the user consents, the approved scopes are recorded.
When scopes are added — If scopes are added to the application later, the consent screen is displayed again at the next authentication. All scopes are shown, including those previously approved.

Once consented, scopes are recorded, so the consent screen will not appear on subsequent logins as long as the scope configuration remains the same.

Client Credentials Flow

This is the authentication flow for server-to-server system authentication. Access tokens are obtained using only client credentials without user involvement. The endpoint differs between SaaS and Marketplace editions.

SaaS

Prerequisites

A system integration (client) is already registered in Console (Console Guide — System Integration)
Client ID, Client Secret, and Token URL have been obtained

Token Retrieval

Execute the following request on the server side.

curl
curl -X POST https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Parameters

grant_type: Fixed as client_credentials
client_id: Client ID obtained from Console
client_secret: Client secret obtained from Console

Response Example

JSON
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid users:read logs:read"
}

Marketplace

Prerequisites

Setup of the AGENTIC STAR environment purchased through Marketplace is complete
A service account has been created in Admin
The following information has been obtained:
- Client ID — Service account client ID
- Client Secret — Service account secret (viewable on Admin detail screen)

Token Retrieval

Execute the following request on the server side.

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

Parameters

<your-domain>: Base URL of your environment (e.g., api.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": 1800,
  "scope": "openid"
}

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

Scopes represent the permissions included in an access token. The operations an application can perform via the API are determined by the assigned scopes.

Scope Assignment

SaaS: Select scopes when creating a client in Console. For applications (AC flow), select Chat API, MCP, and A2A scopes; for system integrations (CC flow), select management API scopes (Console Guide). Available APIs are restricted based on the assigned scopes.
Marketplace: No scope-based restrictions. All APIs are available.

Scope List

AGENTIC STAR agents support three connection methods: Chat API (SSE), MCP, and A2A. The required scopes depend on which connection method you use. See the Connection Guide for details.

Connecting via Chat API (SSE)

Scope	Description
`chat:exec`	Start/stop chat, receive streaming responses, retrieve deliverables. Required when using Chat API.
`chat:history`	Retrieve conversation list and message history (active / archived), delete / rename conversations, restore archived conversations, search messages.
`chat:file`	Upload, retrieve, and delete files used in chat.

Connecting via MCP / A2A

Scope	Description
`mcp:all`	Required when connecting to the agent via MCP (Model Context Protocol).
`a2a:all`	Required when connecting to the agent via A2A (Agent-to-Agent) protocol.

Using Management APIs

Scope	Description
`sharedmemory:query`	Search shared memory.
`users:read`	Read user information (list, details).
`users:manage`	Manage users (approve, revoke approval, delete, change role). Includes `users:read` permissions.
`logs:read`	View logs (audit logs, LLM logs, access logs).
`master:manage`	Manage master data (create, update, delete departments and job types).

Scope Selection Guidance

Selectable Scopes for Applications (AC Flow)

When using Chat API to interact with the agent: chat:exec is required. Add chat:history and chat:file if you need history management or file operations.
When connecting from MCP-compatible AI agents: Select mcp:all.
When connecting from A2A-compatible AI agents: Select a2a:all.
When combining multiple connection methods, you can select scopes from each.

Selectable Scopes for System Integrations (CC Flow)

When using management APIs: Select users:read, users:manage, logs:read, master:manage, sharedmemory:query, etc. based on the operations you need.

Using Access Tokens

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

Authorization: Bearer <access_token>

The same format is used for all API endpoints. See User API Reference for details.

Overview​

Authorization Code Flow (SaaS)​

Prerequisites​

1. Authorization Request​

2. User Authentication​

3. Receive Authorization Code​

4. Obtain Token​

Token Refresh​

Consent Screen​

Information Displayed on the Consent Screen​

When the Consent Screen Appears​

Client Credentials Flow​

SaaS​

Prerequisites​

Token Retrieval​

Marketplace​

Prerequisites​

Token Retrieval​

Token Re-acquisition​

Scopes​

Scope Assignment​

Scope List​

Connecting via Chat API (SSE)​

Connecting via MCP / A2A​

Using Management APIs​

Scope Selection Guidance​

Selectable Scopes for Applications (AC Flow)​

Selectable Scopes for System Integrations (CC Flow)​

Using Access Tokens​

Overview

Authorization Code Flow (SaaS)

Prerequisites

1. Authorization Request

2. User Authentication

3. Receive Authorization Code

4. Obtain Token

Token Refresh

Consent Screen

Information Displayed on the Consent Screen

When the Consent Screen Appears

Client Credentials Flow

SaaS

Prerequisites

Token Retrieval

Marketplace

Prerequisites

Token Retrieval

Token Re-acquisition

Scopes

Scope Assignment

Scope List

Connecting via Chat API (SSE)

Connecting via MCP / A2A

Using Management APIs

Scope Selection Guidance

Selectable Scopes for Applications (AC Flow)

Selectable Scopes for System Integrations (CC Flow)

Using Access Tokens