# Console Guide

The Console is the screen that manages API clients and LLM Gateway keys. It is a different screen from the admin console ([Admin Console Reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/admin/reference/admin-ref.md#notation)).

This guide explains how to create an application or system integration in Console and configure the authentication information and scopes required for API usage.

<!-- -->

## Overview

To use AGENTIC STAR's API, you must first create a client in Console based on your intended use.

|                     | Application                     | System Integration                                          |
| ------------------- | ------------------------------- | ----------------------------------------------------------- |
| Use Case            | Applications where users log in | Server-to-server integration (System Integration API, etc.) |
| Authentication Flow | Authorization Code              | Client Credentials                                          |
| User Authentication | Yes (login via browser)         | No (client credentials only)                                |
| Console Menu        | "App List"                      | "System Integrations"                                       |

> **Prerequisites**
>
> - Ability to log in to Console (developer role or higher)
> - Permission from the organization administrator to use the API
>
> For details, see [Authentication Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/auth-guide.md).

## Steps to Create an Application

Start creation by clicking "New Create" from the "App List" menu in Console.

### 1. Select Application Type

Select the application type based on your use case. The authentication method and security settings are automatically determined based on the type. **The type cannot be changed after creation.**

|                     | Web Application                   | SPA                                             | Mobile / Native                                |
| ------------------- | --------------------------------- | ----------------------------------------------- | ---------------------------------------------- |
| Use Case            | Server-side web applications      | Single Page Applications running in the browser | Mobile apps and desktop apps                   |
| Client Type         | Confidential (with Client Secret) | Public (no Client Secret, PKCE authentication)  | Public (no Client Secret, PKCE authentication) |
| Authentication Flow | Authorization Code                | Authorization Code + PKCE (required)            | Authorization Code + PKCE (required)           |
| Redirect URI        | Required                          | Required                                        | Required                                       |
| Web Origins (CORS)  | Optional                          | Required                                        | —                                              |

> **For SPA / Mobile Applications**
>
> SPA and mobile applications are configured as Public Clients. PKCE (S256) is mandatory and provides protection through challenge verification using `code_challenge` / `code_verifier`. Methods other than S256 (such as plain) are not supported.

### 2. Enter Basic Information

| Item                 | Required | Description                                                                                        |
| -------------------- | -------- | -------------------------------------------------------------------------------------------------- |
| App Name             | ✓        | Display name of the application (max 255 characters). Also displayed on the authorization screen.  |
| Logo                 | ✓        | Logo image of the application (PNG, JPEG, SVG format, max 500KB, recommended 128x128px or larger). |
| Short Description    | ✓        | Concise description within 50 characters. Displayed in the app list.                               |
| Detailed Description | ✓        | Detailed description of the application (max 10,000 characters).                                   |
| Support URL          |          | URL of support page. Displayed on the consent screen.                                              |
| Privacy Policy URL   |          | URL of privacy policy. Displayed on the consent screen.                                            |
| Terms of Use URL     |          | URL of terms of use. Displayed on the consent screen.                                              |

### 3. Technical Configuration

| Item               | Required | Description                                                                                                                                      |
| ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Client ID          | —        | Auto-generated UUID. Cannot be changed. Copy and use after creation.                                                                             |
| Redirect URI       | ✓        | Register one or more redirect destination URLs after authorization completion. Validation is exact match, so enter the precise URL.              |
| Web Origins (CORS) | ※        | Required only for SPA. Register origin URLs to allow direct API calls from the browser. Optional for Web applications. Not displayed for Mobile. |

> **About Redirect URI Registration**
>
> Redirect URI is validated by exact match for security. It is recommended to register both development environment (`http://localhost:3000/callback`) and production environment (`https://yourapp.com/callback`) URLs. Wildcards are not supported.

### 4. Select Scopes

Select the required scopes based on the features your application will use. The selected scopes define the maximum range of permissions available to this application.

For the list of available scopes and selection guidance, see [Authentication Guide — Scopes](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/auth-guide.md#scopes).

> **Write, delete, and decide scopes**
>
> Selecting `project:write`, `project:delete`, or `project:decide` also selects `project:read`, and selecting `assets:write` or `assets:delete` also selects `assets:read`. Clearing a read scope (`project:read` or `assets:read`) also clears the write, delete, and decide scopes of the same area.

### 5. Visibility

Choose who can use the application with the "Available to everyone in the tenant" switch.

| Switch        | Who can use it                                                                        |
| ------------- | ------------------------------------------------------------------------------------- |
| Off (default) | Administrators and developers only. Keeping it off is recommended during development. |
| On            | All users in this tenant.                                                             |

### 6. Consent Screen

Configure whether to enable the consent screen. When enabled, the application name, logo, description, Support URL, Privacy Policy URL, and Terms of Use URL set in the basic information are reflected on the consent screen. Enter these accurately if you plan to enable the consent screen.

For consent screen behavior (display timing, displayed information), see [Authentication Guide — Consent Screen](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/auth-guide.md#consent-screen).

### 7. Complete Creation

Click the "Create" button to create the application. After creation, you will be redirected to the app detail screen where you can view Client ID and Client Secret.

## System Integration Creation Steps

To use the System Integration API server-to-server, create a Client Credentials client from the "System Integrations" menu. No user login is required; access tokens are obtained using only client credentials.

Start creation by clicking "New Create" from the "System Integrations" menu in Console.

### 1. Enter Basic Information

| Item        | Required | Description                                            |
| ----------- | -------- | ------------------------------------------------------ |
| Name        | ✓        | Display name for the integration (max 255 characters). |
| Description |          | Description of the integration purpose and use case.   |

### 2. Select Scopes

Select the required scopes based on the operations you will use in the System Integration API.

For the list of available scopes, see [Authentication Guide — Scopes](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/auth-guide.md#scopes). To use the system integration from MCP, also select `mcp:connect` ([AI Client Connection Guide (MCP)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/ai-client-guide.md)).

> **Write Scopes**
>
> Write scopes such as `users:manage` and `master:manage` involve data modification and deletion. Select only the minimum scopes required.

### 3. Configure Project Restrictions

If you selected `project:read` or `project:run`, configure which projects this integration may operate on.

| Setting                    | Description                                                                                                                    |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Selected projects only     | Enter the IDs of the projects to allow, one per line. Only the projects you enter can be operated on. You can enter up to 100. |
| All projects in the tenant | All projects in the tenant can be operated on, including projects created in the future.                                       |

> **Project restrictions are required**
>
> If you grant `project:*` scopes without configuring a project restriction, **every project API call returns `403 Forbidden`**. An unconfigured restriction is not treated as "All projects in the tenant".
>
> Specifying a project ID outside the configured range returns the same `404 Not Found` as a project that does not exist. Changes take effect from the next access token you obtain.

See [System Integration API Reference — Projects](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/admin-api-reference.md#projects) for the project API specification.

### 4. Complete Creation

Click the "Create" button to create the system integration. After creation, you will be redirected to the detail screen where you can view Client ID, Client Secret, and Token URL.

## Confirm Authentication Information

After creating a client, the authentication information required for API usage can be confirmed on the detail screen.

### Application Authentication Information

The following information can be confirmed on the app detail screen.

- **Client ID** — Displayed in the "Technical Configuration" section. Can be copied to clipboard using the copy button.
- **Client Secret** — Issued for Web applications (Confidential).

| Action     | Description                                                                                             |
| ---------- | ------------------------------------------------------------------------------------------------------- |
| View       | Click the eye icon to display the masked Client Secret.                                                 |
| Copy       | Click the copy icon to copy Client Secret to clipboard.                                                 |
| Regenerate | Click the refresh icon to generate a new Client Secret. The previous secret is immediately invalidated. |

### System Integration Authentication Information

The following information can be confirmed on the system integration detail screen.

- **Client ID** — Can be copied to clipboard using the copy button.
- **Client Secret** — Can be viewed, copied, and regenerated (same operations as Application).
- **Token URL** — URL for obtaining access tokens. Can be copied to clipboard using the copy button.
- **API Key** — You can issue, regenerate, and delete a fixed API key (see "API Key" below).

> **Client Secret Handling**
>
> - Client Secret is confidential information equivalent to a password. Keep it secure.
> - Do not hardcode in source code or version control systems. Environment variables or Secret Manager usage is recommended.
> - Regenerating Client Secret will cause authentication to fail for all systems using the old secret. Check the scope of impact beforehand.

### API Key

On the system integration's detail page, you can issue a fixed API key (`agtstr_…`). Send it as `Authorization: Bearer agtstr_…` to call the API and MCP directly. You don't need to get a new token. It can't be sent in the `x-api-key` header.

| Operation  | Button             | Result                                                                                                                      |
| ---------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| Issue      | Issue API Key      | A new API key is shown.                                                                                                     |
| Regenerate | Regenerate API Key | A new API key is shown, and the previous API key stops working. Update the settings of the connected system to the new key. |
| Delete     | Delete API Key     | Access with that API key stops. Deletion can't be undone.                                                                   |

- Regenerating and deleting take up to about 1 minute to take effect.
- Administrators and developers of the organization can view the API key's value later. A project owner sees it only right after issuing or regenerating it; if you lost it, regenerate it. For a system integration created by a project owner, the API key isn't shown to administrators either.
- Treat the API key as confidential, the same as a Client Secret.

### If Credentials Leak

If credentials of an application or a system integration leak, stop them as follows.

For an **application** (used by people who sign in), stop it as follows, depending on what leaked.

| What leaked                               | How to stop it                                                                                                                                                                    |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Client Secret (Web application)           | Regenerate the Client Secret, or delete the application. After regeneration, tokens can no longer be obtained with the old Secret.                                                |
| A user's token, or the application itself | Delete the application. New sign-ins and token refreshes stop immediately. Deletion cannot be undone, and the application also stops working for other companies that adopted it. |

- The application can be deleted, and its Client Secret regenerated, by the administrators and developers of the organization that created it. SPA and mobile / native applications have no Client Secret, so stop them by deleting them.
- Turning "Available to everyone in the tenant" on or off does not stop tokens already issued. It changes who can access the application.
- The Console has no operation that ends the sessions of only one user.

For a **system integration**, stop it as follows, depending on what leaked.

| What leaked   | How to stop it                                                                                                                                                                 |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Client Secret | Regenerate the Client Secret, or disable the system integration. After regeneration, tokens can no longer be obtained with the old Secret.                                     |
| API key       | Delete that API key, or disable the system integration. Regenerating the Client Secret does not stop access with the API key. It can take up to about 1 minute to take effect. |

- Access tokens already issued may remain usable until they expire (1 hour), even after the application is deleted or the system integration is disabled.
- For an integration managed by project owners, the project owners regenerate the Client Secret and delete the API key. Administrators can only disable or delete it, and cannot enable a disabled integration again.
- With leaked credentials, someone can perform only the operations within the scopes granted to that system integration. For example, with the project scopes: listing projects within the project restriction and reading run status, starting and canceling runs, and firing triggers (for agents that write to external services, external services are affected too). Data that has already been read cannot be taken back.

## Next Steps

After obtaining authentication information, proceed to the following guides based on your use case.

- [Quickstart](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/quickstart/call-api.md) — Shortest route to experience API with curl
- [Authentication Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/auth-guide.md) — Detailed steps for authentication flows
- [User API Reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference.md) — User-facing API endpoint specifications
