Authentication Reference (SaaS)

This is a reference for OIDC endpoint specifications, JWT claim structures, scopes, and error codes for AgenticStar SaaS edition.

Endpoint List

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

Base URL: https://auth.agenticstar.jp/federation

Issuer: https://auth.agenticstar.jp/realms/federation

Discovery

GET /.well-known/openid-configuration

OpenID Connect Discovery endpoint. Clients retrieve endpoint URLs and server information.

Request Example

curl

curl https://auth.agenticstar.jp/federation/.well-known/openid-configuration

Response Example

JSON

{
  "issuer": "https://auth.agenticstar.jp/realms/federation",
  "authorization_endpoint": "https://auth.agenticstar.jp/federation/auth/v1/authorize",
  "token_endpoint": "https://auth.agenticstar.jp/federation/auth/v1/token",
  "userinfo_endpoint": "https://auth.agenticstar.jp/federation/auth/v1/userinfo",
  "jwks_uri": "https://auth.agenticstar.jp/federation/auth/v1/jwks",
  "revocation_endpoint": "https://auth.agenticstar.jp/federation/auth/v1/revoke",
  "end_session_endpoint": "https://auth.agenticstar.jp/federation/auth/v1/logout",
  "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"]
}

Authorization Code Flow

GET /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
scope	string	Required	Space-separated scopes. openid is required
state	string	Required	For CSRF protection. Unpredictable value generated by client
nonce	string	—	For nonce claim insertion into ID Token (recommended)
kc_idp_hint	string	—	Tenant ID hint. Can skip login screen

Request URL Example

curl

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

On Success

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

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

On Error

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
invalid_scope	Requested scope is invalid or missing
server_error	Server-side error

Token Endpoint

POST /auth/v1/token

Obtain an access token (and ID Token) using Authorization Code 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.agenticstar.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

If the service account feature is enabled, tenant information associated with the client is included in the token.

Request Example

curl

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

On Success (200 OK)

JSON

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

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	invalid_scope	Requested scope is invalid

Refresh Token

POST /auth/v1/token (refresh_token grant)

Refresh an access token using a 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.agenticstar.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 Example

JSON

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

UserInfo

GET /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.

Request Headers

Header	Required	Description
Authorization	Required	Bearer <access_token>

Request Example

curl

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

Response Fields

Field	Type	Description
sub	string	User ID (OIDC standard)
idp	object	User information retrieved from IdP (only when via tenant)
idp.sub	string	User ID on IdP side
idp.name	string	Display name
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
502	bad_gateway	Failed to retrieve user information from IdP

JWKS

GET /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.agenticstar.jp/federation/auth/v1/jwks

Response Example

JSON

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

Revoke

POST /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.agenticstar.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"

On success, 204 No Content is returned.

Logout

GET /auth/v1/logout

RP-Initiated Logout endpoint. Terminates user session and redirects to specified URI. Access directly via web browser. A logout confirmation screen is displayed.

Query Parameters

Parameter	Type	Required	Description
id_token_hint	string	Recommended	ID Token. Used to identify client (extracts client_id from JWT azp claim). Required if client_id parameter is not specified.
client_id	string	—	Client ID. Can directly specify client instead of id_token_hint. This takes precedence if both are specified.
post_logout_redirect_uri	string	—	URI to redirect to after logout (pre-registration required)
logout_hint	string	—	Hint information for logout target
state	string	—	State parameter returned during redirection
ui_locales	string	—	Display language of logout screen (e.g., ja)

info

You must identify the client using either id_token_hint or client_id. If neither is specified, you will be redirected to an error page.

Request URL Example

https://auth.agenticstar.jp/federation/auth/v1/logout?\
  id_token_hint=eyJhbGciOiJSUzI1NiJ9...&\
  post_logout_redirect_uri=https%3A%2F%2Fapp.example.com%2F&\
  state=abc123

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

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.agenticstar.jp/federation)
aud	string	Audience. Token target (Client ID)
exp	number	Expiration time (Unix timestamp)
iat	number	Issued at (Unix timestamp)
azp	string	Authorized Party. Client ID that requested the token
scope	string	Granted scopes (space-separated)

Tenant Information (tenant.*)

Information about the tenant (enterprise / SaaS). Included in nested structure in Access Token and ID Token.

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). Included in nested structure. Also output in same structure if linked user is set in 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[]	Roles assigned to user (e.g., user, admin, developer)

JWT Access Token Payload Example

JSON

{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "iss": "https://auth.agenticstar.jp/federation",
  "aud": "my-client",
  "exp": 1704070800,
  "iat": 1704067200,
  "azp": "my-client",
  "scope": "openid chat:all",
  "tenant": {
    "id": "enterprise-a",
    "type": "enterprise",
    "endpoint": "https://enterprise-a.example.com"
  },
  "idp": {
    "sub": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "preferred_username": "user@enterprise-a.com",
    "organization": "Enterprise A Corp.",
    "job": "Engineer",
    "bio": "Software developer"
  },
  "realm_access": {
    "roles": ["user"]
  }
}

Scopes

Scope List

Below are the main scopes. See API Reference for a complete list.

Chat API

• chat:exec - Execute chat
• chat:history - View and delete chat history
• chat:file - File operations
• chat:all - All chat scopes

MCP / A2A

• mcp:exec - Execute task via MCP
• a2a:exec - Execute task via A2A

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.

Scope Assignment Flow

Assign scopes to a client using Client Scope Role Mapping in Console. When generating the token, the scopes actually granted are determined by the following conditions:

• Scopes assigned to the client
• Intersection of scopes permitted by user role (user, admin, developer, etc.)
• As a result, only necessary scopes within the user's role range are included in the token

Error Codes

OAuth 2.0 / OIDC Errors

Error Code	Description	How to Respond
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
204 No Content	Request succeeded (no response body)
302 Found	Redirect (Authorization / Logout endpoints)
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