# 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

| 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                                           |

## 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:

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

### Request Example

**Get discovery document**

**curl**

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

**Python**

```python
import requests

response = requests.get(
  "https://auth.fd.agenticstar.tm.softbank.jp/realms/federation/.well-known/openid-configuration",
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch("https://auth.fd.agenticstar.tm.softbank.jp/realms/federation/.well-known/openid-configuration");
const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://auth.fd.agenticstar.tm.softbank.jp/realms/federation/.well-known/openid-configuration", nil)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

### 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

| Status               | code              | Description                                                                                                                                       |
| -------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| 403                  | `forbidden`       | The 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_request` | The identity provider refused to return the Discovery document (the 4xx status code of the identity provider is returned as is)                   |
| 502                  | `bad_gateway`     | Failed 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_id`     | `string` | 必須 | Client ID                                                                                                                                                                         |
| `redirect_uri`  | `string` | 必須 | URI to redirect to after authorization (must be registered in advance)                                                                                                            |
| `response_type` | `string` | 必須 | Specify code                                                                                                                                                                      |
| `state`         | `string` | —  | 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 |
| `nonce`         | `string` | —  | For inserting a nonce claim into the ID Token (recommended)                                                                                                                       |

### Request Example

```bash
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:

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

### Error Response

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

```text
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

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

### Authorization Code Flow

#### Request Body

| パラメータ           | 型        | 必須 | 説明                                                                              |
| --------------- | -------- | -- | ------------------------------------------------------------------------------- |
| `grant_type`    | `string` | 必須 | Specify authorization\_code                                                     |
| `code`          | `string` | 必須 | The authorization code obtained from the Authorization Code endpoint            |
| `redirect_uri`  | `string` | 必須 | The same value as the redirect\_uri specified in the Authorization Code request |
| `client_id`     | `string` | 必須 | Client ID                                                                       |
| `client_secret` | `string` | 必須 | Client secret (send it securely in backend-to-backend communication)            |

#### Request Example

**Get token (Authorization Code)**

**curl**

```curl
curl -X POST https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/token \
-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"
```

**Python**

```python
import requests

response = requests.post(
  "https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/token",
  data={"grant_type": "authorization_code", "code": "AUTH_CODE", "redirect_uri": "https://app.example.com/callback", "client_id": "my-client", "client_secret": "my-secret"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch("https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/token", {
method: "POST",
body: new URLSearchParams({ grant_type: "authorization_code", code: "AUTH_CODE", redirect_uri: "https://app.example.com/callback", client_id: "my-client", client_secret: "my-secret" }),
});
const data = await response.json();
console.log(data);
```

**Go**

```go
form := url.Values{}
form.Set("grant_type", "authorization_code")
form.Set("code", "AUTH_CODE")
form.Set("redirect_uri", "https://app.example.com/callback")
form.Set("client_id", "my-client")
form.Set("client_secret", "my-secret")
resp, _ := http.PostForm("https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/token", form)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

### Client Credentials Flow

#### Request Body

| パラメータ           | 型        | 必須 | 説明                          |
| --------------- | -------- | -- | --------------------------- |
| `grant_type`    | `string` | 必須 | Specify client\_credentials |
| `client_id`     | `string` | 必須 | Client ID                   |
| `client_secret` | `string` | 必須 | Client secret               |

#### Request Example

**Get token (Client Credentials)**

**curl**

```curl
curl -X POST https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/token \
-d "grant_type=client_credentials" \
-d "client_id=my-m2m-client" \
-d "client_secret=my-secret"
```

**Python**

```python
import requests

response = requests.post(
  "https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/token",
  data={"grant_type": "client_credentials", "client_id": "my-m2m-client", "client_secret": "my-secret"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch("https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/token", {
method: "POST",
body: new URLSearchParams({ grant_type: "client_credentials", client_id: "my-m2m-client", client_secret: "my-secret" }),
});
const data = await response.json();
console.log(data);
```

**Go**

```go
form := url.Values{}
form.Set("grant_type", "client_credentials")
form.Set("client_id", "my-m2m-client")
form.Set("client_secret", "my-secret")
resp, _ := http.PostForm("https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/token", form)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

### 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 | code                      | Description                                                                                                                                                                |
| ------ | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | `invalid_request`         | Required parameters missing or format is invalid                                                                                                                           |
| 400    | `invalid_grant`           | Authorization Code is invalid or expired                                                                                                                                   |
| 400    | `invalid_scope`           | Requested scope is invalid                                                                                                                                                 |
| 401    | `invalid_client`          | Client authentication failed (ID / Secret is incorrect)                                                                                                                    |
| 401    | `unauthorized_client`     | The 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) |
| 413    | `invalid_request`         | The body is too large, or has too many parameters                                                                                                                          |
| 415    | `invalid_request`         | The charset or Content-Encoding of the body is not supported                                                                                                               |
| 502    | `bad_gateway`             | Communication with the authentication platform failed                                                                                                                      |
| 503    | `temporarily_unavailable` | The 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_type`    | `string` | 必須 | Specify refresh\_token                             |
| `refresh_token` | `string` | 必須 | The Refresh Token obtained from the Token endpoint |
| `client_id`     | `string` | 必須 | Client ID                                          |
| `client_secret` | `string` | 必須 | Client secret                                      |

### Request Example

**Refresh token**

**curl**

```curl
curl -X POST https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/token \
-d "grant_type=refresh_token" \
-d "refresh_token=REFRESH_TOKEN" \
-d "client_id=my-client" \
-d "client_secret=my-secret"
```

**Python**

```python
import requests

response = requests.post(
  "https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/token",
  data={"grant_type": "refresh_token", "refresh_token": "REFRESH_TOKEN", "client_id": "my-client", "client_secret": "my-secret"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch("https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/token", {
method: "POST",
body: new URLSearchParams({ grant_type: "refresh_token", refresh_token: "REFRESH_TOKEN", client_id: "my-client", client_secret: "my-secret" }),
});
const data = await response.json();
console.log(data);
```

**Go**

```go
form := url.Values{}
form.Set("grant_type", "refresh_token")
form.Set("refresh_token", "REFRESH_TOKEN")
form.Set("client_id", "my-client")
form.Set("client_secret", "my-secret")
resp, _ := http.PostForm("https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/token", form)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

### Response Fields (200 OK)

The response has the same structure as the Token endpoint. See [Token Endpoint — Response Fields](#token-endpoint).

### 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 | code                      | Description                                                                                  |
| ------ | ------------------------- | -------------------------------------------------------------------------------------------- |
| 400    | `invalid_request`         | Required parameters missing or format is invalid                                             |
| 400    | `invalid_grant`           | Refresh Token is invalid or expired                                                          |
| 401    | `invalid_client`          | Client authentication failed (ID / Secret is incorrect)                                      |
| 401    | `unauthorized_client`     | The conditions for using the client are not met (for example, the user's tenant is disabled) |
| 413    | `invalid_request`         | The body is too large, or has too many parameters                                            |
| 415    | `invalid_request`         | The charset or Content-Encoding of the body is not supported                                 |
| 502    | `bad_gateway`             | Communication with the authentication platform failed                                        |
| 503    | `temporarily_unavailable` | The 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**

**curl**

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

**Python**

```python
import requests

response = requests.get(
  "https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/userinfo",
  headers={"Authorization": "Bearer <access_token>"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch("https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/userinfo", {
headers: { "Authorization": "Bearer <access_token>" },
});
const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/userinfo", nil)
req.Header.Set("Authorization", "Bearer <access_token>")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

### 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 | code                      | Description                                                                                          |
| ------ | ------------------------- | ---------------------------------------------------------------------------------------------------- |
| 401    | `invalid_token`           | Token is invalid or expired                                                                          |
| 413    | `invalid_request`         | The body is too large, or has too many parameters                                                    |
| 415    | `invalid_request`         | The charset or Content-Encoding of the body is not supported                                         |
| 429    | `temporarily_unavailable` | The request limit of the IdP was exceeded. If a Retry-After header is present, retry after that time |
| 500    | `server_error`            | Configuration error in the authentication platform 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

**Get JWKS**

**curl**

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

**Python**

```python
import requests

response = requests.get(
  "https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/jwks",
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch("https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/jwks");
const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/jwks", nil)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

### 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"
    }
  ]
}
```

### Error Response

| Status | code          | Description                                                |
| ------ | ------------- | ---------------------------------------------------------- |
| 502    | `bad_gateway` | Failed 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

| パラメータ           | 型        | 必須 | 説明                                                  |
| --------------- | -------- | -- | --------------------------------------------------- |
| `token`         | `string` | 必須 | The token to revoke (Access Token or Refresh Token) |
| `client_id`     | `string` | 必須 | Client ID                                           |
| `client_secret` | `string` | 必須 | Client secret                                       |

### Request Example

**Revoke token**

**curl**

```curl
curl -X POST https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/revoke \
-d "token=ACCESS_TOKEN" \
-d "client_id=my-client" \
-d "client_secret=my-secret"
```

**Python**

```python
import requests

response = requests.post(
  "https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/revoke",
  data={"token": "ACCESS_TOKEN", "client_id": "my-client", "client_secret": "my-secret"},
)

print(response.status_code)
```

**TypeScript**

```typescript
const response = await fetch("https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/revoke", {
method: "POST",
body: new URLSearchParams({ token: "ACCESS_TOKEN", client_id: "my-client", client_secret: "my-secret" }),
});
console.log(response.status);
```

**Go**

```go
form := url.Values{}
form.Set("token", "ACCESS_TOKEN")
form.Set("client_id", "my-client")
form.Set("client_secret", "my-secret")
resp, _ := http.PostForm("https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/revoke", form)
defer resp.Body.Close()
fmt.Println(resp.StatusCode)
```

### 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 | code              | Description                                                  |
| ------ | ----------------- | ------------------------------------------------------------ |
| 400    | `invalid_request` | Required parameters missing or format is invalid             |
| 401    | `invalid_client`  | Client authentication failed (ID / Secret is incorrect)      |
| 413    | `invalid_request` | The body is too large, or has too many parameters            |
| 415    | `invalid_request` | The charset or Content-Encoding of the body is not supported |
| 502    | `bad_gateway`     | Communication 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

```text
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:connect`        | Connect via MCP (Model Context Protocol); which tools you can use depends on the other scopes you hold                                                                                                                                                                                                                                                                                                                                               |
| `mcp:all`            | Use all MCP tools                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `a2a:connect`        | Connect via the A2A (Agent-to-Agent) protocol (the operations you can use depend on the other scopes you hold)                                                                                                                                                                                                                                                                                                                                       |
| `a2a:all`            | Use all A2A operations                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `sharedmemory:query` | Query shared memory                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `users:read`         | Read user information (list and details)                                                                                                                                                                                                                                                                                                                                                                                                             |
| `users:manage`       | User management operations (create / approve / revoke approval / delete / change role / suspend and resume / unlock / change affiliation and job). Includes read permission                                                                                                                                                                                                                                                                          |
| `logs:read`          | View logs (audit logs, operation audit logs, user action audit, LLM logs, LLM Gateway logs, LLM Gateway operation audit, access logs, guardrail alerts)                                                                                                                                                                                                                                                                                              |
| `master:manage`      | Manage master data (create, update, and delete organizations and job types)                                                                                                                                                                                                                                                                                                                                                                          |
| `project:read`       | Read 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:run`        | Start project runs, fire triggers, and cancel workflow runs (for applications, also rerun failed sweeps and resume closed workflow runs)                                                                                                                                                                                                                                                                                                             |
| `project:write`      | Create 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:delete`     | Delete projects you own (applications only)                                                                                                                                                                                                                                                                                                                                                                                                          |
| `project:decide`     | Decide 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:read`        | View Agents, Playbooks, and Skills (applications only)                                                                                                                                                                                                                                                                                                                                                                                               |
| `assets:write`       | Create, edit, and copy Agents, Playbooks, and Skills (applications only)                                                                                                                                                                                                                                                                                                                                                                             |
| `assets:delete`      | Delete Agents, Playbooks, and Skills (applications only)                                                                                                                                                                                                                                                                                                                                                                                             |

For details on each scope and guidance on selection, see [Authentication Guide — Scopes](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/auth-guide.md#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                                                   |
| `temporarily_unavailable` | The 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

| 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                                          |
| `413 Payload Too Large`      | The body is too large, or has too many parameters             |
| `415 Unsupported Media Type` | The charset or Content-Encoding of the body is not supported  |
| `429 Too Many Requests`      | The request limit of the IdP was exceeded (UserInfo endpoint) |
| `500 Internal Server Error`  | Server internal error                                         |
| `502 Bad Gateway`            | Communication with the authentication platform failed         |
