# Authentication API Reference

This is a reference for authentication endpoint specifications, JWT claim structure, and error codes for Marketplace edition. There are token endpoints for service accounts (system integrations) and endpoints for sign-in from an external tool (applications).

## Base URL

The token endpoints for service accounts use the following base URL of the authentication service. Replace `<auth-domain>` with the domain of the authentication service that the administrator decided when building the environment (for example, `auth.example.com`). The endpoints for sign-in from an external tool are on the domain of the external entrance of the authorization server ([Sign-in from an External Tool](#external-login)).

Marketplace

`https://<auth-domain>`

## Authentication Endpoint List

Marketplace

Obtain an access token with the Client Credentials flow using service account credentials.

| Method | Endpoint                              | Description                                                                                             |
| ------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| POST   | `/api/v1/oauth/token`                 | Token endpoint in the standard form (RFC 6749). Issues an access token via the Client Credentials flow. |
| POST   | `/api/v1/auth/external-service-token` | The earlier token endpoint. Issues an access token via the Client Credentials flow.                     |
| GET    | `/.well-known/jwks.json`              | JWKS endpoint. Returns the public key set for JWT signature verification.                               |

> **Creating a Service Account**
>
> To use the API, create a service account in the admin console and obtain the Client ID and Client Secret ([API Setup Guide — Creating a System Integration](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/setup-guide.md#service-account)).

## Standard Token Endpoint

### POST`/api/v1/oauth/token`

Issues an access token via the Client Credentials flow. The request, response, and errors are in the form of RFC 6749 ([RFC 6749 4.4](https://www.rfc-editor.org/rfc/rfc6749#section-4.4)).

### Request Headers

| ヘッダー            | 必須 | 説明                                                                                            |
| --------------- | -- | --------------------------------------------------------------------------------------------- |
| `Content-Type`  | 必須 | application/x-www-form-urlencoded                                                             |
| `Authorization` | —  | Add this when authenticating the client with Basic authentication (\`client\_secret\_basic\`) |

### Request Body

| パラメータ           | 型        | 必須 | 説明                                                                                 |
| --------------- | -------- | -- | ---------------------------------------------------------------------------------- |
| `grant_type`    | `string` | 必須 | Specify client\_credentials                                                        |
| `client_id`     | `string` | —  | Specify this when authenticating the client in the body (\`client\_secret\_post\`) |
| `client_secret` | `string` | —  | Specify this when authenticating the client in the body (\`client\_secret\_post\`) |

Authenticate the client with either Basic authentication in the `Authorization` header or `client_id` and `client_secret` in the body, not both. Sending both returns `400` (`invalid_request`).

### Request Example

**Get token (Client Credentials)**

**curl**

```curl
curl -X POST https://<auth-domain>/api/v1/oauth/token \
-u "your_client_id:your_client_secret" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials"
```

**Python**

```python
import requests

response = requests.post(
  "https://<auth-domain>/api/v1/oauth/token",
  auth=("your_client_id", "your_client_secret"),
  data={"grant_type": "client_credentials"},
)

print(response.json())
```

**TypeScript**

```typescript
const credentials = btoa("your_client_id:your_client_secret");
const response = await fetch("https://<auth-domain>/api/v1/oauth/token", {
method: "POST",
headers: {
  "Authorization": "Basic " + credentials,
  "Content-Type": "application/x-www-form-urlencoded",
},
body: new URLSearchParams({ grant_type: "client_credentials" }),
});

const data = await response.json();
console.log(data);
```

**Go**

```go
form := url.Values{}
form.Set("grant_type", "client_credentials")
req, _ := http.NewRequest("POST", "https://<auth-domain>/api/v1/oauth/token", strings.NewReader(form.Encode()))
req.SetBasicAuth("your_client_id", "your_client_secret")
req.Header.Set("Content-Type", "application/x-www-form-urlencoded")

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                                                   |
| -------------- | -------- | ------------------------------------------------------------- |
| `access_token` | `string` | Access token in JWT format                                    |
| `token_type`   | `string` | Bearer                                                        |
| `expires_in`   | `number` | Access token expiration time (seconds)                        |
| `scope`        | `string` | Granted scopes (space-separated; omitted when there are none) |

The response has `Cache-Control: no-store`. Refresh tokens are not issued.

### Error Response

| Status | code                  | Description                                                                                                                                                                                                                                                                                                  |
| ------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400`  | `invalid_request`     | The client authentication was sent with both methods, or the client\_id in Basic authentication differs from the client\_id in the body                                                                                                                                                                      |
| `401`  | `invalid_client`      | There is no client authentication, or the Client ID / Secret is incorrect (with a WWW-Authenticate header)                                                                                                                                                                                                   |
| `429`  | `rate_limit_exceeded` | Too many requests from the same source and Client ID. Retry after a while (if a Retry-After header is present, wait that many seconds). The body of this response is not the form of 400, 401, and 500 above (where `error` is the code); it has `success`, `error` (the description), `message`, and `code` |
| `500`  | `server_error`        | The token cannot be issued (retry after a while)                                                                                                                                                                                                                                                             |

The body of 400, 401, and 500 is `{"error": "...", "error_description": "..."}`, and "code" in the table above is the value of `error`. Only for 429, the value in the table is in the `code` field.

## Token Endpoint

### POST`/api/v1/auth/external-service-token`

The earlier token endpoint. Issues an access token via the Client Credentials flow. Authenticate using service account credentials (Client ID / Client Secret). For new systems, we recommend the [Standard Token Endpoint](#oauth-token).

### Request Headers

| ヘッダー           | 必須 | 説明                                                                                                                                            |
| -------------- | -- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `Content-Type` | —  | application/json. Required when sending client\_id and client\_secret as a JSON body (not needed when sending with Basic authentication only) |

### Request Body

| パラメータ           | 型        | 必須 | 説明                                                                 |
| --------------- | -------- | -- | ------------------------------------------------------------------ |
| `client_id`     | `string` | 必須 | Client ID of the service account (issued in the admin console)     |
| `client_secret` | `string` | 必須 | Client Secret of the service account (issued in the admin console) |

### Request Example

**Get token (service account)**

**curl**

```curl
curl -X POST https://<auth-domain>/api/v1/auth/external-service-token \
-H "Content-Type: application/json" \
-d '{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret"
}'
```

**Python**

```python
import requests

response = requests.post(
  "https://<auth-domain>/api/v1/auth/external-service-token",
  json={"client_id": "your_client_id", "client_secret": "your_client_secret"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch("https://<auth-domain>/api/v1/auth/external-service-token", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
  client_id: "your_client_id",
  client_secret: "your_client_secret",
}),
});

const data = await response.json();
console.log(data);
```

**Go**

```go
payload, _ := json.Marshal(map[string]string{
  "client_id":     "your_client_id",
  "client_secret": "your_client_secret",
})
resp, _ := http.Post("https://<auth-domain>/api/v1/auth/external-service-token", "application/json", bytes.NewBuffer(payload))
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                            |
| -------------- | --------- | -------------------------------------- |
| `success`      | `boolean` | Request success (true on success)      |
| `access_token` | `string`  | Access token in JWT format             |
| `token_type`   | `string`  | Bearer                                 |
| `expires_in`   | `number`  | Access token expiration time (seconds) |
| `scope`        | `string`  | Granted scopes (space-separated)       |

### Response Example

```json
{
  "success": true,
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "openid profile email"
}
```

> **note**
>
> The Client Credentials flow does not issue refresh tokens. If the token expires, obtain a new token using the same procedure.

### Error Response

| Status | code                  | Description                                                                                                      |
| ------ | --------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `400`  | `missing_parameters`  | client\_id or client\_secret is missing                                                                          |
| `401`  | `auth_error`          | Client authentication failed (Client ID / Secret is incorrect)                                                   |
| `429`  | `rate_limit_exceeded` | Too many requests from the same source. Retry later (if a Retry-After header is present, wait that many seconds) |
| `500`  | `server_error`        | Server internal error (including when the authentication platform cannot be reached)                             |

```json
{
  "success": false,
  "error": "Invalid credentials",
  "message": "Invalid credentials",
  "code": "auth_error"
}
```

## JWKS Endpoint

### GET`/.well-known/jwks.json`

Returns the JSON Web Key Set (JWKS) for JWT signature verification. Use this when verifying access token signatures.

### Request Example

**Get JWKS**

**curl**

```curl
curl https://<auth-domain>/.well-known/jwks.json
```

**Python**

```python
import requests

response = requests.get(
  "https://<auth-domain>/.well-known/jwks.json",
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch("https://<auth-domain>/.well-known/jwks.json");
const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://<auth-domain>/.well-known/jwks.json", 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[].kid` | `string` | Key ID. Match against the kid in the JWT header to identify the verification key |
| `keys[].kty` | `string` | Key type (e.g., "RSA")                                                           |
| `keys[].alg` | `string` | Algorithm (e.g., "RS256")                                                        |
| `keys[].use` | `string` | Key usage. "sig" (signature verification)                                        |
| `keys[].n`   | `string` | RSA public key modulus (Base64url encoded)                                       |
| `keys[].e`   | `string` | RSA public key exponent (Base64url encoded)                                      |

### Response Headers

| Header          | Description           |
| --------------- | --------------------- |
| `Cache-Control` | `public, max-age=600` |

### Response Example

```json
{
  "keys": [
    {
      "kid": "...",
      "kty": "RSA",
      "alg": "RS256",
      "use": "sig",
      "n": "...",
      "e": "AQAB"
    }
  ]
}
```

> **note**
>
> If key rotation occurs, the `kid` (Key ID) will change. When verifying signatures, use the key that matches the `kid` in the JWT header. Keys can be cached, but periodic re-fetching is recommended.

## Sign-in from an External Tool

The endpoints for sign-in from an external tool (the Authorization Code flow + PKCE). They are available only in environments where an administrator has opened the external entrance of the authorization server ([API Setup Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/setup-guide.md)). All of them are standard OpenID Connect endpoints.

The issuer (`iss`) is `https://<authorization-server-domain>/realms/<realm>`. The authorization server that MCP clients find is also this value ([MCP API Reference — Authentication](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/mcp-ref.md#authentication)).

| Method | Endpoint                                                 | Description                                                                                  |
| ------ | -------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| GET    | `/realms/<realm>/.well-known/openid-configuration`       | Discovery document (OpenID Connect Discovery). Contains the addresses of the endpoints below |
| GET    | `/.well-known/oauth-authorization-server/realms/<realm>` | Discovery document (RFC 8414)                                                                |
| GET    | `/realms/<realm>/protocol/openid-connect/auth`           | Authorization endpoint                                                                       |
| POST   | `/realms/<realm>/protocol/openid-connect/token`          | Token endpoint (exchanging authorization codes and refreshing with refresh tokens)           |
| GET    | `/realms/<realm>/protocol/openid-connect/certs`          | Public keys for verifying signatures (JWKS)                                                  |
| GET    | `/realms/<realm>/protocol/openid-connect/userinfo`       | User information                                                                             |
| GET    | `/realms/<realm>/protocol/openid-connect/logout`         | Sign-out                                                                                     |
| POST   | `/realms/<realm>/protocol/openid-connect/revoke`         | Token revocation                                                                             |

- All addresses are paths relative to `https://<authorization-server-domain>`
- PKCE (`code_challenge_method=S256`) is required at the authorization endpoint. The client is a public client, so do not send `client_secret` to the token endpoint
- There is no endpoint for registering clients automatically (dynamic client registration)
- For an example of the steps, see [Authentication Guide — Authorization Code Flow](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/auth-guide.md#authorization-code)

Access tokens issued by these endpoints are user tokens. `sub` is the user ID, `azp` is the client ID, and `email` is included. There is no `client_id` claim.

## JWT Claims Structure

The structure of JWT claims (payload) contained in the access token of a service account. The signing algorithm is RS256.

### Standard Claims

| Claim   | Type     | Description                                                                                                                          |
| ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `sub`   | `string` | Service account ID (UUID)                                                                                                            |
| `iss`   | `string` | Issuer URL. It is the internal address of the authorization server (`http://<internal-authorization-server-address>/realms/<realm>`) |
| `aud`   | `string` | Fixed value `"account"`                                                                                                              |
| `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)                                                                                                     |
| `acr`   | `string` | Authentication Context Class                                                                                                         |

### User Information

Internal identifiers auto-generated by the authentication platform when a service account is created. They do not represent a real user, so applications do not need to display or use them.

| Claim                | Type      | Description                                                           |
| -------------------- | --------- | --------------------------------------------------------------------- |
| `email`              | `string`  | Internal identifier assigned by the authentication platform           |
| `email_verified`     | `boolean` | Internal flag assigned by the authentication platform (always `true`) |
| `preferred_username` | `string`  | Internal identifier assigned by the authentication platform           |

### Service Account Information

| Claim           | Type     | Description               |
| --------------- | -------- | ------------------------- |
| `client_id`     | `string` | Client ID                 |
| `clientHost`    | `string` | Request source host       |
| `clientAddress` | `string` | Request source IP address |

### Roles

Role information used for internal control by the authentication platform. Applications do not need to reference these roles.

| Claim                           | Type       | Description                                                        |
| ------------------------------- | ---------- | ------------------------------------------------------------------ |
| `realm_access.roles`            | `string[]` | List of realm-level roles assigned by the authentication platform  |
| `resource_access.account.roles` | `string[]` | List of client-level roles assigned by the authentication platform |

### JWT Access Token Payload Example

```json
{
  "exp": 1776713919,
  "iat": 1776627519,
  "jti": "trrtcc:abc12345-6789-4def-8abc-0123456789ab",
  "iss": "http://<internal-authorization-server-address>/realms/<realm>",
  "aud": "account",
  "sub": "11111111-2222-3333-4444-555555555555",
  "typ": "Bearer",
  "azp": "my-service-account",
  "acr": "1",
  "realm_access": {
    "roles": ["..."]
  },
  "resource_access": {
    "account": {
      "roles": ["..."]
    }
  },
  "scope": "openid email profile",
  "email_verified": true,
  "clientHost": "192.168.1.100",
  "preferred_username": "service-account-my-service-account",
  "clientAddress": "192.168.1.100",
  "email": "my-service-account@serviceaccount.local",
  "client_id": "my-service-account"
}
```

## Client Authentication

At the earlier token endpoint (`/api/v1/auth/external-service-token`), perform client authentication using one of the following methods.

### JSON Body

Include `client_id` and `client_secret` as JSON in the request body.

```json
{"client_id": "xxx", "client_secret": "yyy"}
```

### Basic Authentication (Recommended)

Send via Basic authentication in the Authorization header. Request body is not required.

```text
Authorization: Basic base64(client_id:client_secret)
```

### Request Example with Basic Authentication

```bash
curl -X POST https://<auth-domain>/api/v1/auth/external-service-token \
  -u "your_client_id:your_client_secret"
```

## Error Codes

The earlier token endpoint (`/api/v1/auth/external-service-token`) returns error responses in JSON format. All error responses include `success: false`. For the errors of the standard token endpoint, see [Standard Token Endpoint](#oauth-token).

### Error Response Format

| Field     | Type      | Description                         |
| --------- | --------- | ----------------------------------- |
| `success` | `boolean` | Always false                        |
| `error`   | `string`  | Error message                       |
| `message` | `string`  | Error message (same as error)       |
| `code`    | `string`  | Error code (for machine processing) |

```json
{
  "success": false,
  "error": "client_id and client_secret are required",
  "message": "client_id and client_secret are required",
  "code": "missing_parameters"
}
```

### Error Code List

| Status | code                  | Description                                                                                                      |
| ------ | --------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `400`  | `missing_parameters`  | Required parameters (client\_id / client\_secret) are missing                                                    |
| `401`  | `auth_error`          | Client authentication failed (Client ID / Secret is incorrect)                                                   |
| `429`  | `rate_limit_exceeded` | Too many requests from the same source. Retry later (if a Retry-After header is present, wait that many seconds) |
| `500`  | `server_error`        | Server internal error (including when the authentication platform cannot be reached)                             |
