# Authentication API Reference

This is a reference for authentication endpoint specifications, JWT claim structure, and error codes for Marketplace edition.

## Base URL

The base URL of the APIs is shown below. The token endpoint (`/api/v1/auth/external-service-token`) and the JWKS endpoint (`/.well-known/jwks.json`), however, are on the domain of the authentication service (`<auth-domain>`). The domains are the values set when the environment was built.

Marketplace

`https://<your-domain>`

## Authentication Endpoint List

Marketplace

Marketplace edition provides authentication endpoints that support the Client Credentials flow. Obtain an access token using service account credentials and use the API.

| Method | Endpoint                              | Description                                                               |
| ------ | ------------------------------------- | ------------------------------------------------------------------------- |
| POST   | `/api/v1/auth/external-service-token` | 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. Refer to the admin console documentation for service account creation steps.

## Token Endpoint

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

Issues an access token via the Client Credentials flow. Authenticate using service account credentials (Client ID / Client Secret).

### 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**
>
> Marketplace edition 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.

## JWT Claims Structure

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

### Standard Claims

| Claim   | Type     | Description                                               |
| ------- | -------- | --------------------------------------------------------- |
| `sub`   | `string` | Service account ID (UUID)                                 |
| `iss`   | `string` | Issuer URL (e.g., `https://<your-domain>/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": "https://<your-domain>/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 token endpoint, 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 authentication endpoint returns error responses in JSON format. All error responses include `success: false`.

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