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 for your use case.

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

For detailed specifications, see the Authentication API Reference. For the Marketplace edition, see the Authentication Guide (Marketplace).

Authorization Code Flow

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, zh-CN, zh-TW, pt-BR, de-DE, it-IT, ko, vi

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.

Handling Refresh Tokens

• Use the latest token: A new refresh_token is issued each time you refresh. Save the new refresh_token returned in the response and use it for subsequent requests. Do not reuse previous refresh_token values.
• Avoid sharing or concurrent use: Do not share the same refresh_token across multiple processes or instances, or refresh it concurrently. Obtain and manage tokens separately for each client.

Consent Screen

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.

Information Displayed on the Consent Screen

• 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.

When the Consent Screen Appears

• 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.

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

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

• Select scopes when creating a client in Console. For applications (AC flow), select Chat API, MCP, A2A, project, and library scopes; for system integrations (CC flow), select System Integration API and project scopes (Console Guide). Available APIs are restricted based on the assigned scopes.

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 the System Integration API

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).

Operating on Projects

Required when you operate on projects through the API. For the specification, see User API Reference — Projects for applications, or System Integration API Reference — Projects for system integrations.

Scope	Description
project:read	Read projects. For applications, view member projects, their runs, records, and review requests. For system integrations, list the projects within the project restriction and read run status.
project:run	Start project runs and fire triggers on cycle projects.
project:write	Create projects and edit projects you own. Applications only.
project:delete	Delete projects you own. Applications only.
project:decide	Decide review requests assigned to you. Applications only.

Operating on the Library

Required when you operate on Agents, Playbooks, and Skills through the API. Available to applications only. For the specification, see the User API Reference.

Scope	Description
assets:read	View Agents, Playbooks, and Skills. The skill and playbook lists can also be called with chat:exec.
assets:write	Create, edit, and copy Agents, Playbooks, and Skills.
assets:delete	Delete Agents, Playbooks, and Skills.

Notes on project and library scopes

• Wildcards are not supported. project:*, project:all, assets:*, and assets:all do not grant access. Select each scope you need individually.
• project:write, project:delete, project:decide, assets:read, assets:write, and assets:delete are available to applications (AC flow) only. They are not included in system integration tokens.
• Write, delete, and decide scopes are used together with the read scope of the same area. project:write, project:delete, and project:decide require project:read, and assets:write and assets:delete require assets:read. When you select them in Console, the read scope is selected as well.
• Scopes do not select projects. Which projects you can operate on is determined by the project restriction in Console for system integrations, and by the user's participation in the project for applications.
• For applications (AC flow), viewing projects requires membership, while editing and deleting projects and starting runs and firing triggers require ownership, and deciding review requests is limited to the assigned reviewers.

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 operating on projects: Select project:read (read), project:run (start runs / fire triggers), project:write (create / edit), project:delete (delete), and project:decide (decide review requests) as needed.
• When operating on the library (Agents, Playbooks, Skills): Select assets:read (view), assets:write (create / edit / copy), and assets:delete (delete) as needed.
• When combining multiple connection methods, you can select scopes from each.

Selectable Scopes for System Integrations (CC Flow)

• When using the System Integration API: Select users:read, users:manage, logs:read, master:manage, sharedmemory:query, etc. based on the operations you need.
• When operating on projects: Select project:read for read-only access, and add project:run to start runs or fire triggers. Also configure the project restriction in Console (Console Guide — Configuring project restrictions).

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.

When changes to a user's permissions take effect

• Among the APIs called with an application token, operations whose handling depends on whether the user is a system administrator are judged by the role the user had when they last signed in to the AGENTIC STAR UI. After you change a role, it does not take effect until the user signs in to the UI.
• Even after a user is disabled, access tokens already issued may remain usable until they expire (1 hour).