# 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.)                              |
| **APIs you can call**   | User API (chat, conversations, files, projects and more), MCP, A2A | System Integration API (including part of projects) and part of MCP. Chat cannot be used |
| **Token Retrieval**     | Obtained via authorization code                                    | Obtained directly with client credentials                                                |
| **Refresh Token**       | Yes                                                                | No (re-acquire after expiration)                                                         |
| **Required screen**     | Console                                                            | Console                                                                                  |

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

## 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](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/console-guide.md))
- `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.

```text
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](#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.

> **Who Can Access the Application**
>
> Who can access the application depends on the "Available to everyone in the tenant" switch in the Console. See [Console Guide — Visibility](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/console-guide.md#5-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`).

```text
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.

```bash
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.

```bash
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](#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](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/console-guide.md) 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.

Instead of getting a token, a system integration can also send an API key issued in the Console in `Authorization: Bearer` (see [Console Guide — API Key](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/console-guide.md#api-key)).

### Prerequisites

- A system integration (client) is already registered in Console ([Console Guide — System Integration](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/console-guide.md#system-integration-creation-steps))
- `Client ID`, `Client Secret`, and `Token URL` have been obtained

### Token Retrieval

Execute the following request on the server side.

```bash
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, project, and MCP scopes ([Console Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/console-guide.md)). 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](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/connection-guide.md) 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:connect` | Required when connecting via MCP (Model Context Protocol). Which tools you can use depends on the other scopes you hold ([MCP API Reference — Provided Tools](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/mcp-ref.md#provided-tools)). For a new app, we recommend selecting this and the scopes of the tools you use.                                                                                                                                                   |
| `mcp:all`     | Use all MCP tools. No other scope is needed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `a2a:connect` | Required when connecting to the agent via A2A (Agent-to-Agent) protocol. Which operations you can use depends on the other scopes you hold (`chat:exec` to send, get, cancel and resubscribe; `chat:file` in addition to attach files; `chat:history` to list tasks — [A2A API Reference — Authentication](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/a2a-ref.md#authentication)). For a new app, we recommend selecting this and the scopes of the operations you use. |
| `a2a:all`     | Use all A2A operations. No other scope is needed.                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

#### Using the System Integration API

| Scope                | Description                                                                                                                                                      |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sharedmemory:query` | Search shared memory.                                                                                                                                            |
| `users:read`         | Read user information (list, details).                                                                                                                           |
| `users:manage`       | Manage users (create, approve, revoke approval, delete, change role, suspend and resume, unlock, change affiliation and job). Includes `users:read` permissions. |
| `logs:read`          | View logs (audit logs, operation audit logs, user action audit, LLM logs, LLM Gateway logs, LLM Gateway operation audit, access logs, guardrail alerts).         |
| `master:manage`      | Manage master data (create, update, delete organizations and job types).                                                                                         |

#### Operating on Projects

Required when you operate on projects through the API. For the specification, see [User API Reference — Projects](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference.md#projects) for applications, or [System Integration API Reference — Projects](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/admin-api-reference.md#projects) for system integrations.

| Scope            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project:read`   | Read projects. For applications, view the projects you take part in and the projects you can read through the organization operations role, with their runs, records, review requests, queues, and project libraries (the organization operations role cannot read project libraries or review requests; review requests still appear as queue rows). For system integrations, list the projects within the project restriction and read run status. |
| `project:run`    | Start project runs, fire triggers on `cycle` projects, and cancel workflow runs. For applications, also rerun failed sweeps and resume closed workflow runs.                                                                                                                                                                                                                                                                                         |
| `project:write`  | Create projects and edit projects you own (changing the deadline and reassigning the reviewers of workflow runs, and pausing or resuming a project, also in projects where you are an operator or have the organization operations role), and register, change, and delete files in project libraries. Applications only.                                                                                                                            |
| `project:delete` | Delete projects you own. Applications only.                                                                                                                                                                                                                                                                                                                                                                                                          |
| `project:decide` | Decide review requests assigned to you (including those you can decide as a reviewer's delegate during the delegation period) and extend due dates of review requests (owners, operators, and people with the organization operations role can also extend them). 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](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference.md).

| 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 and the organization operations role** for applications.
> - For applications (AC flow), listing projects requires membership, while individual projects and run status can be read by members and people with the organization operations role (the Agent's outputs and similar fields are not shown to people with the organization operations role). Starting runs and firing triggers are open to members and people with the organization operations role. Canceling a workflow run is open to owners and operators (including people with the organization operations role) and the person who started that run. Changing the deadline and reassigning the reviewers of workflow runs, rerunning failed sweeps, resuming closed workflow runs (including getting the resume options), and pausing or resuming projects require the owner or operator role (including people with the organization operations role); other edits and deleting projects require ownership; deciding review requests is limited to the assigned reviewers and their delegates during the delegation period; and extending due dates is also open to owners, operators, and people with the organization operations role.

### 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:connect` and the scopes of the tools you use (for example, `chat:exec` for chat, `project:read` to read projects). To use all MCP tools, you can also select `mcp:all`.
- **When connecting from A2A-compatible AI agents**: Select `a2a:connect` and the scopes of the operations you use (`chat:exec` to send, get, cancel and resubscribe; `chat:file` in addition to attach files; `chat:history` to list tasks). To use all A2A operations, you can also select `a2a:all`.
- **When operating on projects**: Select `project:read` (read), `project:run` (start runs / fire triggers / rerun failed sweeps / resume closed workflow runs / cancel workflow runs), `project:write` (create / edit), `project:delete` (delete), and `project:decide` (decide review requests / extend due dates) 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, fire triggers, or cancel workflow runs. Also configure the project restriction in Console ([Console Guide — Configuring project restrictions](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/console-guide.md#project-restriction)).
- **When using it from MCP**: Add `mcp:connect`. A system integration can use the five operations of the MCP project set and `list_personas` ([AI Client Connection Guide (MCP)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/ai-client-guide.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 [User API Reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference.md) 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).
