Authentication API Reference (SaaS)

Reference for OIDC endpoint specifications, JWT claim structures, scopes, and error codes for AGENTIC STAR SaaS edition.

Endpoint List

SaaS

Method	Endpoint	Description
GET	/realms/federation/.well-known/openid-configuration	OpenID Connect Discovery endpoint
GET	/federation/auth/v1/authorize	User authorization endpoint for Authorization Code flow
POST	/federation/auth/v1/token	Token acquisition endpoint (supports AC / CC / Refresh Token flows)
GET / POST	/federation/auth/v1/userinfo	User information retrieval endpoint (supports both GET and POST)
GET	/federation/auth/v1/jwks	JSON Web Key Set (JWKS) endpoint
POST	/federation/auth/v1/revoke	Token revocation endpoint

Host: https://auth.fd.agenticstar.tm.softbank.jp

Issuer: https://auth.fd.agenticstar.tm.softbank.jp/realms/federation

Discovery

GET/realms/federation/.well-known/openid-configuration

Clients retrieve the necessary endpoint URLs and server information.

As a compatibility alias, the same response is also returned at the RFC 8414 (OAuth 2.0 Authorization Server Metadata) path:

GET /realms/federation/.well-known/oauth-authorization-server

Request Example

curl

curl https://auth.fd.agenticstar.tm.softbank.jp/realms/federation/.well-known/openid-configuration

Response Example

JSON

{
  "issuer": "https://auth.fd.agenticstar.tm.softbank.jp/realms/federation",
  "authorization_endpoint": "https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/authorize",
  "token_endpoint": "https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/token",
  "userinfo_endpoint": "https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/userinfo",
  "jwks_uri": "https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/jwks",
  "revocation_endpoint": "https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/revoke",
  "grant_types_supported": ["authorization_code", "client_credentials", "refresh_token"],
  "response_types_supported": ["code"],
  "response_modes_supported": ["query"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256"],
  "token_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post"],
  "code_challenge_methods_supported": ["S256"]
}

Authorization Code Flow

GET/federation/auth/v1/authorize

User authenticates and authorizes the application to obtain an Authorization Code. Access directly via web browser.

Query Parameters

Parameter	Type	Required	Description
client_id	string	Required	Client ID
redirect_uri	string	Required	URI to redirect to after authorization (pre-registration required)
response_type	string	Required	Specify code
state	string	Recommended	For CSRF protection. Unpredictable value generated by the client. If specified, it is returned in the response, so verify that it matches the value sent in the request
nonce	string	—	For nonce claim insertion into ID Token (recommended)

Request Example

curl

https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/authorize?\
  client_id=my-client&\
  redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&\
  response_type=code&\
  state=abc123xyz&\
  nonce=xyz789abc

Response (302 Redirect)

If user authorization is successful, redirection occurs in the following format:

https://app.example.com/callback?\
  code=AUTH_CODE&\
  state=abc123xyz

Error Response

If an error occurs, redirection occurs in the following format:

https://app.example.com/callback?\
  error=invalid_scope&\
  error_description=...&\
  state=abc123xyz

Error Code	Description
invalid_request	Required parameters missing or format is invalid
unauthorized_client	Client is not authorized to use authorization flow
unsupported_response_type	response_type is not code (this service only supports code)
access_denied	Client is disabled or access was denied
invalid_scope	Requested scope is invalid or missing
server_error	Server-side error

Token Endpoint

POST/federation/auth/v1/token

Obtain an access token using Authorization Code flow or Client Credentials flow.

Request Headers

Header	Required	Description
Content-Type	Required	application/x-www-form-urlencoded

Authorization Code Flow

Request Body

Parameter	Type	Required	Description
grant_type	string	Required	Specify authorization_code
code	string	Required	Authorization code obtained from Authorization Code endpoint
redirect_uri	string	Required	Same value as redirect_uri specified when requesting Authorization Code
client_id	string	Required	Client ID
client_secret	string	Required	Client Secret (transmit securely over backend communication)

Request Example

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" \
  -d "redirect_uri=https://app.example.com/callback" \
  -d "client_id=my-client" \
  -d "client_secret=my-secret"

Client Credentials Flow

Request Body

Parameter	Type	Required	Description
grant_type	string	Required	Specify client_credentials
client_id	string	Required	Client ID
client_secret	string	Required	Client Secret

Request Example

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=my-m2m-client" \
  -d "client_secret=my-secret"

Response Fields (200 OK)

Field	Type	Description
access_token	string	Access token in JWT format
id_token	string	ID Token in JWT format
expires_in	number	Access token expiration time (seconds)
refresh_expires_in	number	Refresh token expiration time (seconds). AC flow only
refresh_token	string	Refresh token (used for token renewal). AC flow only
token_type	string	"Bearer"
scope	string	Granted scopes (space-separated)

Response Example (Authorization Code Flow)

JSON

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "id_token": "eyJhbGciOiJSUzI1NiIs...",
  "expires_in": 3600,
  "refresh_expires_in": 86400,
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "scope": "openid chat:exec chat:history chat:file"
}

Response Example (Client Credentials Flow)

JSON

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "id_token": "eyJhbGciOiJSUzI1NiIs...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "openid users:read logs:read"
}

Client Credentials Flow Response

The Client Credentials flow does not issue a refresh token. The refresh_token and refresh_expires_in fields are not included in the response.

Error Response

Status	Error Code	Description
400	invalid_request	Required parameters missing or format is invalid
401	invalid_client	Client authentication failed (ID / Secret is incorrect)
400	invalid_grant	Authorization Code is invalid or expired
400	unauthorized_client	Client conditions are not met (e.g., user tenant is disabled, or the client is in "Unpublished" state and developer role is required)
400	invalid_scope	Requested scope is invalid
502	bad_gateway	Communication with the authentication platform (KC) failed

Refresh Token

POST/federation/auth/v1/token

Refresh an access token using a Refresh Token. Specify grant_type=refresh_token.

Request Body

Parameter	Type	Required	Description
grant_type	string	Required	Specify refresh_token
refresh_token	string	Required	Refresh Token obtained from Token endpoint
client_id	string	Required	Client ID
client_secret	string	Required	Client Secret

Request Example

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" \
  -d "client_id=my-client" \
  -d "client_secret=my-secret"

Response Fields (200 OK)

The response has the same structure as the Token endpoint. See Token Endpoint — Response Fields.

Response Example

JSON

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "id_token": "eyJhbGciOiJSUzI1NiIs...",
  "expires_in": 3600,
  "refresh_expires_in": 86400,
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "scope": "openid chat:exec chat:history chat:file"
}

Error Response

Status	Error Code	Description
400	invalid_request	Required parameters missing or format is invalid
401	invalid_client	Client authentication failed (ID / Secret is incorrect)
400	invalid_grant	Refresh Token is invalid or expired
502	bad_gateway	Communication with the authentication platform (KC) failed

UserInfo

GET/federation/auth/v1/userinfo

Retrieve user information using a valid access token. For tenant-based authentication, the idp block contains IdP user information in addition to OIDC standard claims.

Conforming to OIDC Core 1.0 §5.3, both GET and POST return the same response. When using POST, authenticate with the Authorization: Bearer <access_token> header as well.

Request Headers

Header	Required	Description
Authorization	Required	Bearer <access_token>

Request Example

curl

curl https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/userinfo \
  -H "Authorization: Bearer <access_token>"

Response Fields (200 OK)

Field	Type	Description
sub	string	User ID (OIDC standard)
idp	object	User information retrieved from IdP (only for tenant-based authentication)
idp.sub	string	User ID on IdP side
idp.name	string	Username
idp.preferred_username	string	Username (email address)
idp.email	string	Email address
idp.email_verified	boolean	Whether email address is verified
idp.organization	object	Organization (includes id and label)
idp.job	object	Job title (includes id and label)
idp.bio	string	Bio

Response Example

JSON

{
  "sub": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "idp": {
    "sub": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "yamada_taro",
    "preferred_username": "taro.yamada@example.com",
    "email": "taro.yamada@example.com",
    "email_verified": true,
    "organization": {
      "id": "org-001",
      "label": "Example Corp."
    },
    "job": {
      "id": "job-001",
      "label": "Engineer"
    },
    "bio": "Software engineer"
  }
}

Error Response

Status	Error Code	Description
401	invalid_token	Token is invalid or expired
500	server_error	Configuration error in the authentication platform (KC) or IdP
502	bad_gateway	Failed to retrieve user information from IdP

JWKS

GET/federation/auth/v1/jwks

Retrieve a JSON Web Key Set (JWKS) for JWT signature verification. Use this to verify the signatures of ID Tokens and Access Tokens.

Request Example

curl

curl https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/jwks

Response Fields (200 OK)

Field	Type	Description
keys	array	Array of JWK (JSON Web Key) objects
keys[].kty	string	Key type (e.g., "RSA")
keys[].kid	string	Key ID. Matched against the kid in JWT header to identify the key used for verification
keys[].use	string	Key usage. "sig" (signature verification)
keys[].alg	string	Algorithm (e.g., "RS256")
keys[].n	string	RSA public key modulus (Base64url encoded)
keys[].e	string	RSA public key exponent (Base64url encoded)

Response Example

JSON

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "key-id-1",
      "use": "sig",
      "alg": "RS256",
      "n": "modulus...",
      "e": "AQAB"
    }
  ]
}

Revoke

POST/federation/auth/v1/revoke

Revoke an access token or Refresh Token.

Request Headers

Header	Required	Description
Content-Type	Required	application/x-www-form-urlencoded

Request Body

Parameter	Type	Required	Description
token	string	Required	Token to revoke (Access Token or Refresh Token)
client_id	string	Required	Client ID
client_secret	string	Required	Client Secret

Request Example

curl

curl -X POST https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/revoke \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=ACCESS_TOKEN" \
  -d "client_id=my-client" \
  -d "client_secret=my-secret"

Response Fields (200 OK)

On success, 200 OK is returned with an empty response body. Even if the token is already invalid, 200 OK is returned (RFC 7009 compliant).

Error Response

Status	Error Code	Description
400	invalid_request	Required parameters missing or format is invalid
401	invalid_client	Client authentication failed (ID / Secret is incorrect)
502	bad_gateway	Communication with the authentication platform (KC) failed

JWT Specification

ID Token and Access Token are issued in JWT format. JWT is signed (signing algorithm: RS256) and consists of three parts: header.payload.signature.

JWT Structure

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyLWlk....signature_part

Header

JSON

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "key-id-1"
}

Payload (Claims)

See the following sections for a detailed list of claims.

Claims List

Standard Claims

Claims included in both AC (Authorization Code) and CC (Client Credentials) flow tokens.

Claim	Type	Description
sub	string	Subject ID. UUID that uniquely identifies a user or service account within the authentication platform
iss	string	Issuer. Token issuer (https://auth.fd.agenticstar.tm.softbank.jp/realms/federation)
exp	number	Expiration time (Unix timestamp)
iat	number	Issued at (Unix timestamp)
jti	string	JWT ID. Unique identifier for the token
typ	string	Token type ("Bearer")
azp	string	Authorized Party. Client ID that requested the token
scope	string	Granted scopes (space-separated)
preferred_username	string	User name (CC flow only, format: service-account-<client-id>@federation.invalid)

AC Flow-Specific Claims

Claims included only in tokens issued by the Authorization Code flow.

Claim	Type	Description
aud	string	Audience. Fixed value "broker" (internal target identifier of the authentication platform)
sid	string	Session ID. Authentication session identifier
auth_time	number	Time when user authentication was completed (Unix timestamp)
allowed-origins	string[]	Allowed origins (for CORS)

Tenant Information (tenant.*)

Information about the tenant (enterprise / SaaS). Included in nested structure in Access Token and ID Token for both AC and CC flows.

Claim	Type	Description	Token
tenant.id	string	Tenant ID	AT / IDT
tenant.type	string	enterprise or saas	AT / IDT
tenant.endpoint	string	Tenant endpoint URL	AT / IDT

IdP Profile (idp.*)

User information retrieved from IdP (enterprise authentication platform). In the AC flow, the logged-in user's information is included in nested structure. The idp.* block is not included in the CC flow.

Claim	Type	Description	Token
idp.sub	string	IdP User ID	AT / IDT
idp.preferred_username	string	IdP username (email address)	AT / IDT
idp.display_name	string	Display name	IDT
idp.email	string	Email address	IDT
idp.organization	string	Organization	AT / IDT
idp.job	string	Job title	AT / IDT
idp.bio	string	Bio	AT / IDT

Roles

Claim	Type	Description
realm_access.roles	string[]	Realm roles. In AC flow, roles assigned to the user (e.g., user, admin, developer); in CC flow, fixed to ["M2M"]
resource_access.<client>.roles	string[]	Client-specific roles (may be granted in AC flow only)

Access Token Payload Example (Authorization Code Flow)

JSON

{
  "exp": 1745049600,
  "iat": 1745048100,
  "jti": "onrtac:abc12345-6789-4def-8abc-0123456789ab",
  "iss": "https://auth.fd.agenticstar.tm.softbank.jp/realms/federation",
  "aud": "broker",
  "sub": "11111111-2222-3333-4444-555555555555",
  "typ": "Bearer",
  "azp": "my-client",
  "sid": "99999999-8888-7777-6666-555555555555",
  "allowed-origins": ["http://localhost:4000"],
  "realm_access": {
    "roles": ["admin", "developer", "user"]
  },
  "resource_access": {
    "broker": { "roles": ["read-token"] }
  },
  "scope": "openid mcp:all chat:file chat:history email a2a:all profile chat:exec",
  "auth_time": 1745048090,
  "tenant": {
    "id": "enterprise-a",
    "type": "enterprise",
    "endpoint": "https://enterprise-a.example.com"
  },
  "idp": {
    "sub": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "organization": "Enterprise A Division",
    "bio": "Software developer",
    "preferred_username": "user@enterprise-a.com",
    "job": "Engineer"
  }
}

Access Token Payload Example (Client Credentials Flow)

JSON

{
  "exp": 1745049600,
  "iat": 1745048100,
  "jti": "trrtcc:abc12345-6789-4def-8abc-0123456789ab",
  "iss": "https://auth.fd.agenticstar.tm.softbank.jp/realms/federation",
  "sub": "22222222-3333-4444-5555-666666666666",
  "typ": "Bearer",
  "azp": "my-cc-client",
  "realm_access": {
    "roles": ["M2M"]
  },
  "scope": "openid sharedmemory:query users:manage master:manage logs:read users:read",
  "preferred_username": "service-account-my-cc-client@federation.invalid",
  "tenant": {
    "id": "enterprise-a",
    "type": "enterprise",
    "endpoint": "https://enterprise-a.example.com"
  }
}

note

• The AC flow includes aud (fixed to "broker"), sid, auth_time, and allowed-origins, which are not present in the CC flow.
• In the AC flow, realm_access.roles reflects the user roles assigned in the Console; in the CC flow, it is fixed to "M2M".

Scopes

Scope List

Scope	Description
chat:exec	Start/stop chat, receive streaming responses, retrieve artifacts
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
mcp:all	Connect to agents via MCP (Model Context Protocol)
a2a:all	Connect to agents via A2A (Agent-to-Agent) protocol
sharedmemory:query	Query shared memory
users:read	Read user information (list and details)
users:manage	User management operations (approve / revoke approval / delete / change role). Includes read permission
logs:read	View logs (audit logs, LLM logs, access logs)
master:manage	Manage master data (create, update, and delete departments and job types)

For details on each scope and guidance on selection, see Authentication Guide — Scopes.

Scope Control Mechanism

By assigning scopes to a client in Console, the scopes included in the token are determined. Only scopes permitted by the user's role are granted in the token.

Error Codes

OAuth 2.0 / OIDC Errors

Error Code	Description	Resolution
invalid_request	Required parameters missing or format is invalid	Check request parameters
unauthorized_client	Client is not authorized, or Client ID is incorrect	Check Client ID and configuration
invalid_client	Client authentication failed (ID / Secret is incorrect)	Check Client ID and Secret
invalid_grant	Authorization Code is invalid, expired, or already used	Obtain a new Authorization Code
invalid_scope	Requested scope is invalid or not assigned	Assign scope to client in Console
server_error	Server-side error such as communication error with authentication platform	Wait a while and try again. If the problem persists, contact support
invalid_token	Token is invalid or expired	Obtain a new token

HTTP Status Codes

Status	Description
200 OK	Request succeeded
302 Found	Redirect (Authorization endpoint)
400 Bad Request	Request is invalid
401 Unauthorized	Authentication failed or token is invalid
403 Forbidden	Request is forbidden
500 Internal Server Error	Server internal error
502 Bad Gateway	Communication with the authentication platform failed