Skip to main content

SaaS Quickstart

This guide walks you through obtaining a token using Authorization Code authentication and conversing with an agent via SSE.

Introduction​

Here are the quickest steps to use the SaaS API. You can start conversing with an agent in just four steps.

Scope of this Quickstart

This quickstart targets Web applications (Confidential Clients that can keep a Client Secret on the server side). For SPAs / mobile apps (Public Clients), the PKCE flow is required, so this quickstart cannot be used as-is. See the Authentication Guide for details.

Prerequisites
  • API option subscription is activated
  • Ability to log in to Console (developer role or higher)
  • A Web application type client has been created in Console (Console Guide)
  • You have obtained the following information:
    • Client ID - The ID of the created application
    • Client Secret - The application secret
    • Redirect URI - The redirect URL registered in Console

Step 1: Verify Authentication Information​

Verify the following information on the app detail screen in Console.

Example​

Client ID: your-app-001
Client Secret: (hidden)
Redirect URI: http://localhost:3000/callback

Step 2: Obtain Authorization Code​

Access the authorization endpoint in your browser, log in, and obtain an authorization code.

Construct Authorization URL​

Open the following URL in your browser. Replace client_id, redirect_uri, and state with your own values.

https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/authorize?response_type=code&client_id=<your-client-id>&redirect_uri=<your-redirect-uri>&state=<random-state-value>

Parameters​

  • response_type: Fixed as code
  • client_id: Client ID verified in Step 1
  • redirect_uri: Redirect URI registered in Console (URL-encoded)
  • state: Random string for CSRF protection (strongly recommended)

Login and Authorization​

  1. A login screen appears in the browser. Log in with your usual account.
  2. If the application has the consent screen enabled, it is displayed on first use or when scopes are added. Review the content and grant permission.

Receive Authorization Code​

After authorization, the browser redirects to redirect_uri. The code parameter in the URL is the authorization code.

http://localhost:3000/callback?code=AUTH_CODE_VALUE&state=<random-state-value>
warning
  • If state is specified, always verify that the value in the response matches the value from your request (CSRF protection)
  • The authorization code has a short expiration, so exchange it for a token immediately in the next step

Step 3: Obtain Token​

Exchange the authorization code for an access token. Execute the following request from your server.

Request Example​

Exchange authorization code for token
1curl -X POST https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/token \
2-H "Content-Type: application/x-www-form-urlencoded" \
3-d "grant_type=authorization_code" \
4-d "code=<auth-code>" \
5-d "redirect_uri=<your-redirect-uri>" \
6-d "client_id=<your-client-id>" \
7-d "client_secret=<your-client-secret>"

Parameters​

  • grant_type: Fixed as authorization_code
  • code: Authorization code obtained in Step 2
  • redirect_uri: Same Redirect URI as Step 2
  • client_id: Client ID verified in Step 1
  • client_secret: Client Secret verified in Step 1

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

The token is valid for the number of seconds specified in expires_in. After expiration, you can refresh the token using refresh_token. See the Authentication Guide for details.

Step 4: Call Chat API​

Use the obtained access token to call the Chat API via SSE (Server-Sent Events). You will receive real-time responses from the agent in stream format.

Request Example​

Create chat completion
1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/chat/completions \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5  "model": "AGENTIC STAR",
6  "stream": true,
7  "messages": [
8    {
9      "role": "user",
10      "content": "Hello"
11    }
12  ]
13}'

Parameters​

  • <access_token>: Access token obtained in Step 3
  • stream: true: Enable SSE streaming
  • messages: Message from user. Multiple messages can be sent in array format

Response Example (SSE Stream)​

data: {"choices":[{"delta":{"content":"Hello"}}]}

data: {"choices":[{"delta":{"content":", how can I"}}]}

data: {"choices":[{"delta":{"content":"help you?"}}]}

data: [DONE]

For readability, the snippet above only shows delta.content. Actual chunks include additional fields such as createdAt / model / choices[].index / finishReason. See the API Reference for the complete format.

About SSE Streaming

The response is in Server-Sent Events (SSE) format, sent in real-time in chunks. Each chunk is in the format data: JSON. The conversation completes with data: [DONE]. See Streaming Guide for details.

Next Steps​

For more detailed information and implementation patterns, see the following documentation.

⚙️Console Guide
SaaS

Application creation, scope settings, and authentication information

🔑Authentication Guide
SaaS

Authentication flow details and token refresh

🔌Connection Guide
SaaS

Compare and choose SSE, MCP, and A2A

⚡Streaming Guide
SaaS

SSE connection lifecycle, event handling, reconnection, error handling