Authentication Guide

This guide explains how to obtain access tokens using AgenticStar SaaS authentication flows (Authorization Code / Client Credentials).

Overview

AgenticStar SaaS provides OIDC (OpenID Connect) standard-compliant authentication. You can choose from two authentication flows depending on your use case.

Authentication Flows

• Authorization Code Flow Used when end users (individuals) log in via a browser. Users obtain access tokens and refresh tokens through an authorization screen.

• Client Credentials Flow Used for server-to-server communication or system authentication where users are not involved. Access tokens are obtained using only client credentials.

For detailed specifications, see the Authentication Reference.

Prerequisites

Confirm that the following preparations are complete:

• An application (client) is already registered in Console (admin panel)
• client_id and client_secret have been obtained
• If using Authorization Code flow, the redirect URI (redirect_uri) is already registered

Authorization Code Flow

This is the authentication flow for when users log in via a browser. In four steps, you obtain access tokens and refresh tokens.

Step 1: Authorization Request

Redirect the user to the authorization endpoint in a browser. The user proceeds through the login screen to authorize the request.

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

Parameters

• response_type: Fixed as code
• client_id: Client ID obtained from Console
• redirect_uri: Registered redirect URI
• state: Random value for CSRF attack prevention

Step 2: User Authentication

When you access the authorization endpoint, a tenant selection screen appears first. A tenant identifies your AgenticStar environment. After selecting a tenant, the login screen for your AgenticStar environment is displayed. Log in using the same authentication method as your usual account. Once authentication is complete, an authorization code is issued and returned to the redirect URI.

Step 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

Notes

• Verify that the returned state 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

Step 4: Obtain Token

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

curl

# POST リクエスト例（curl）
curl -X POST https://auth.agenticstar.com/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 the request
• client_id: Client ID obtained from Console
• client_secret: Client secret obtained from Console (keep it secure)

Response Example

JSON

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid chat:all mcp:all"
}

Notes

• Use access_token in the Authorization header of API requests: Authorization: Bearer {access_token}
• Save refresh_token to refresh the token when it expires

Client Credentials Flow

This is the authentication flow for server-to-server communication or other cases where users are not involved. Access tokens are obtained directly using only client credentials.

Token Request

Obtain access tokens directly using client credentials.

curl

# POST request example (curl)
curl -X POST https://auth.agenticstar.com/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...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid chat:all"
}

About Refresh Tokens

The Client Credentials flow does not issue refresh tokens (refresh_token). After the access token expires, execute the same request again.

Token Refresh

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

curl

# POST request example (curl)
curl -X POST https://auth.agenticstar.com/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...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Best Practices

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.

Scopes

Scopes represent the permissions included in the access token. Assign the required scopes to your client in Console. The token will include scopes assigned to the client that are also permitted by the user's role.

Scope	Description
Chat
chat:all	All chat functionality (includes all below)
chat:exec	Chat execution (start, stop, real-time response, deliverable retrieval)
chat:history	Chat history (conversation list, deletion)
chat:file	File operations (upload, retrieval, deletion)
MCP
mcp:all	All MCP functionality (includes all below)
mcp:exec	MCP execution
mcp:file	MCP file attachment
A2A
a2a:all	All A2A functionality (includes all below)
a2a:exec	Agent-to-Agent execution
a2a:file	A2A file attachment