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.
https://<your-domain>Authentication Endpoint List
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. |
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
1curl -X POST https://<auth-domain>/api/v1/auth/external-service-token \2-H "Content-Type: application/json" \3-d '{4 "client_id": "your_client_id",5 "client_secret": "your_client_secret"6}'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"
}'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())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);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
{
"success": true,
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 86400,
"scope": "openid profile email"
}
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) |
{
"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
1curl https://<auth-domain>/.well-known/jwks.jsoncurl https://<auth-domain>/.well-known/jwks.json
import requests response = requests.get( "https://<auth-domain>/.well-known/jwks.json", ) print(response.json())
const response = await fetch("https://<auth-domain>/.well-known/jwks.json");
const data = await response.json();
console.log(data);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
{
"keys": [
{
"kid": "...",
"kty": "RSA",
"alg": "RS256",
"use": "sig",
"n": "...",
"e": "AQAB"
}
]
}
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
{
"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.
{"client_id": "xxx", "client_secret": "yyy"}
Basic Authentication (Recommended)
Send via Basic authentication in the Authorization header. Request body is not required.
Authorization: Basic base64(client_id:client_secret)
Request Example with Basic Authentication
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) |
{
"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) |