Skip to main content

Authentication API Reference

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

Base URL​

All requests are sent to the following base URL.

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

Issuer​

This value matches the iss claim of the ID token and the issuer value in the Discovery response.

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

Endpoint List​

SaaS
MethodEndpointDescription
GET/realms/federation/.well-known/openid-configurationOpenID Connect Discovery endpoint
GET/federation/auth/v1/authorizeUser authorization endpoint for Authorization Code flow
POST/federation/auth/v1/tokenToken acquisition endpoint (supports AC / CC / Refresh Token flows)
GET / POST/federation/auth/v1/userinfoUser information retrieval endpoint (supports both GET and POST)
GET/federation/auth/v1/jwksJSON Web Key Set (JWKS) endpoint
POST/federation/auth/v1/revokeToken revocation endpoint

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​

Get discovery document
1curl 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", "refresh_token", "client_credentials"],
"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"]
}

Error Response​

StatuscodeDescription
403forbiddenThe specified realm does not exist or cannot be used (the same response as a request to a path that is not allowed; the two cannot be told apart)
4xx (other than 404)invalid_requestThe identity provider refused to return the Discovery document (the 4xx status code of the identity provider is returned as is)
502bad_gatewayFailed to fetch the Discovery document from the identity provider (the identity provider returned 5xx or could not be reached)

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​

パラメータ型必須説明
client_idstring必須Client ID
redirect_uristring必須URI to redirect to after authorization (must be registered in advance)
response_typestring必須Specify code
statestring—Recommended. For CSRF protection. An unpredictable value generated by the client. It is returned in the response if specified, so verify that it matches the value in the request
noncestring—For inserting a nonce claim into the 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 CodeDescription
invalid_requestRequired parameters missing or format is invalid
unauthorized_clientClient is not authorized to use authorization flow
unsupported_response_typeresponse_type is not code (this service only supports code)
access_deniedClient is disabled or access was denied
invalid_scopeRequested scope is invalid or missing
server_errorServer-side error

Token Endpoint​

POST/federation/auth/v1/token

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

Request Headers​

ヘッダー必須説明
Content-Type必須application/x-www-form-urlencoded

Authorization Code Flow​

Request Body​

パラメータ型必須説明
grant_typestring必須Specify authorization_code
codestring必須The authorization code obtained from the Authorization Code endpoint
redirect_uristring必須The same value as the redirect_uri specified in the Authorization Code request
client_idstring必須Client ID
client_secretstring必須Client secret (send it securely in backend-to-backend communication)

Request Example​

Get token (Authorization Code)
1curl -X POST https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/token \
2-d "grant_type=authorization_code" \
3-d "code=AUTH_CODE" \
4-d "redirect_uri=https://app.example.com/callback" \
5-d "client_id=my-client" \
6-d "client_secret=my-secret"

Client Credentials Flow​

Request Body​

パラメータ型必須説明
grant_typestring必須Specify client_credentials
client_idstring必須Client ID
client_secretstring必須Client secret

Request Example​

Get token (Client Credentials)
1curl -X POST https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/token \
2-d "grant_type=client_credentials" \
3-d "client_id=my-m2m-client" \
4-d "client_secret=my-secret"

Response Fields (200 OK)​

FieldTypeDescription
access_tokenstringAccess token in JWT format
id_tokenstringID Token in JWT format
expires_innumberAccess token expiration time (seconds)
refresh_expires_innumberRefresh token expiration time (seconds). AC flow only
refresh_tokenstringRefresh token (used for token renewal). AC flow only
token_typestring"Bearer"
scopestringGranted 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​

StatuscodeDescription
400invalid_requestRequired parameters missing or format is invalid
400invalid_grantAuthorization Code is invalid or expired
400invalid_scopeRequested scope is invalid
401invalid_clientClient authentication failed (ID / Secret is incorrect)
401unauthorized_clientThe conditions for using the client are not met (for example, the user's tenant is disabled, or the client is in the "private" state and the developer role is required)
413invalid_requestThe body is too large, or has too many parameters
415invalid_requestThe charset or Content-Encoding of the body is not supported
502bad_gatewayCommunication with the authentication platform failed
503temporarily_unavailableThe state of the user's tenant could not be checked. Retry after a while

Refresh Token​

POST/federation/auth/v1/token

Refresh an access token using a Refresh Token. Specify grant_type=refresh_token. The response includes a new refresh_token each time you refresh.

Request Body​

パラメータ型必須説明
grant_typestring必須Specify refresh_token
refresh_tokenstring必須The Refresh Token obtained from the Token endpoint
client_idstring必須Client ID
client_secretstring必須Client secret

Request Example​

Refresh token
1curl -X POST https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/token \
2-d "grant_type=refresh_token" \
3-d "refresh_token=REFRESH_TOKEN" \
4-d "client_id=my-client" \
5-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​

StatuscodeDescription
400invalid_requestRequired parameters missing or format is invalid
400invalid_grantRefresh Token is invalid or expired
401invalid_clientClient authentication failed (ID / Secret is incorrect)
401unauthorized_clientThe conditions for using the client are not met (for example, the user's tenant is disabled)
413invalid_requestThe body is too large, or has too many parameters
415invalid_requestThe charset or Content-Encoding of the body is not supported
502bad_gatewayCommunication with the authentication platform failed
503temporarily_unavailableThe state of the user's tenant could not be checked. Retry after a while

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​

ヘッダー必須説明
Authorization必須Bearer <access_token>

Request Example​

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

Response Fields (200 OK)​

FieldTypeDescription
substringUser ID (OIDC standard)
idpobjectUser information retrieved from IdP (only for tenant-based authentication)
idp.substringUser ID on IdP side
idp.namestringUsername
idp.preferred_usernamestringUsername (email address)
idp.emailstringEmail address
idp.email_verifiedbooleanWhether email address is verified
idp.organizationobjectOrganization (includes id and label)
idp.jobobjectJob title (includes id and label)
idp.biostringBio

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​

StatuscodeDescription
401invalid_tokenToken is invalid or expired
413invalid_requestThe body is too large, or has too many parameters
415invalid_requestThe charset or Content-Encoding of the body is not supported
429temporarily_unavailableThe request limit of the IdP was exceeded. If a Retry-After header is present, retry after that time
500server_errorConfiguration error in the authentication platform or IdP
502bad_gatewayFailed 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​

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

Response Fields (200 OK)​

FieldTypeDescription
keysarrayArray of JWK (JSON Web Key) objects
keys[].ktystringKey type (e.g., "RSA")
keys[].kidstringKey ID. Matched against the kid in JWT header to identify the key used for verification
keys[].usestringKey usage. "sig" (signature verification)
keys[].algstringAlgorithm (e.g., "RS256")
keys[].nstringRSA public key modulus (Base64url encoded)
keys[].estringRSA public key exponent (Base64url encoded)

Response Example​

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

Error Response​

StatuscodeDescription
502bad_gatewayFailed to fetch the public keys from the identity provider

Revoke​

POST/federation/auth/v1/revoke

Revoke an access token or Refresh Token.

Request Headers​

ヘッダー必須説明
Content-Type必須application/x-www-form-urlencoded

Request Body​

パラメータ型必須説明
tokenstring必須The token to revoke (Access Token or Refresh Token)
client_idstring必須Client ID
client_secretstring必須Client secret

Request Example​

Revoke token
1curl -X POST https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/revoke \
2-d "token=ACCESS_TOKEN" \
3-d "client_id=my-client" \
4-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​

StatuscodeDescription
400invalid_requestRequired parameters missing or format is invalid
401invalid_clientClient authentication failed (ID / Secret is incorrect)
413invalid_requestThe body is too large, or has too many parameters
415invalid_requestThe charset or Content-Encoding of the body is not supported
502bad_gatewayCommunication with the authentication platform 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
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.

ClaimTypeDescription
substringSubject ID. UUID that uniquely identifies a user or service account within the authentication platform
issstringIssuer. Token issuer (https://auth.fd.agenticstar.tm.softbank.jp/realms/federation)
expnumberExpiration time (Unix timestamp)
iatnumberIssued at (Unix timestamp)
jtistringJWT ID. Unique identifier for the token
typstringToken type ("Bearer")
azpstringAuthorized Party. Client ID that requested the token
scopestringGranted scopes (space-separated)
preferred_usernamestringUser 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.

ClaimTypeDescription
audstringAudience. Fixed value "broker" (internal target identifier of the authentication platform)
sidstringSession ID. Authentication session identifier
auth_timenumberTime when user authentication was completed (Unix timestamp)
allowed-originsstring[]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.

ClaimTypeDescriptionToken
tenant.idstringTenant IDAT / IDT
tenant.typestringenterprise or saasAT / IDT
tenant.endpointstringTenant endpoint URLAT / 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.

ClaimTypeDescriptionToken
idp.substringIdP User IDAT / IDT
idp.preferred_usernamestringIdP username (email address)AT / IDT
idp.display_namestringDisplay nameIDT
idp.emailstringEmail addressIDT
idp.organizationstringOrganizationAT / IDT
idp.jobstringJob titleAT / IDT
idp.biostringBioAT / IDT

Roles​

ClaimTypeDescription
realm_access.rolesstring[]Realm roles. In AC flow, roles assigned to the user (e.g., user, admin, developer); in CC flow, fixed to ["M2M"]
resource_access.<client>.rolesstring[]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​

ScopeDescription
chat:execStart/stop chat, receive streaming responses, retrieve artifacts
chat:historyRetrieve conversation list and message history (active / archived), delete / rename conversations, restore archived conversations, search messages
chat:fileUpload, retrieve, and delete files used in chat
mcp:connectConnect via MCP (Model Context Protocol); which tools you can use depends on the other scopes you hold
mcp:allUse all MCP tools
a2a:connectConnect via the A2A (Agent-to-Agent) protocol (the operations you can use depend on the other scopes you hold)
a2a:allUse all A2A operations
sharedmemory:queryQuery shared memory
users:readRead user information (list and details)
users:manageUser management operations (create / approve / revoke approval / delete / change role / suspend and resume / unlock / change affiliation and job). Includes read permission
logs:readView logs (audit logs, operation audit logs, user action audit, LLM logs, LLM Gateway logs, LLM Gateway operation audit, access logs, guardrail alerts)
master:manageManage master data (create, update, and delete organizations and job types)
project:readRead 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:runStart project runs, fire triggers, and cancel workflow runs (for applications, also rerun failed sweeps and resume closed workflow runs)
project:writeCreate 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:deleteDelete projects you own (applications only)
project:decideDecide 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)
assets:readView Agents, Playbooks, and Skills (applications only)
assets:writeCreate, edit, and copy Agents, Playbooks, and Skills (applications only)
assets:deleteDelete Agents, Playbooks, and Skills (applications only)

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 CodeDescriptionResolution
invalid_requestRequired parameters missing or format is invalidCheck request parameters
unauthorized_clientClient is not authorized, or Client ID is incorrectCheck Client ID and configuration
invalid_clientClient authentication failed (ID / Secret is incorrect)Check Client ID and Secret
invalid_grantAuthorization Code is invalid, expired, or already usedObtain a new Authorization Code
invalid_scopeRequested scope is invalid or not assignedAssign scope to client in Console
server_errorServer-side error such as communication error with authentication platformWait a while and try again. If the problem persists, contact support
invalid_tokenToken is invalid or expiredObtain a new token
temporarily_unavailableThe request limit of the IdP was exceeded (429 from the UserInfo endpoint)If a Retry-After header is present, retry after that time

HTTP Status Codes​

StatusDescription
200 OKRequest succeeded
302 FoundRedirect (Authorization endpoint)
400 Bad RequestRequest is invalid
401 UnauthorizedAuthentication failed or token is invalid
403 ForbiddenRequest is forbidden
413 Payload Too LargeThe body is too large, or has too many parameters
415 Unsupported Media TypeThe charset or Content-Encoding of the body is not supported
429 Too Many RequestsThe request limit of the IdP was exceeded (UserInfo endpoint)
500 Internal Server ErrorServer internal error
502 Bad GatewayCommunication with the authentication platform failed