Authentication API Reference (MP)

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

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.

Base URL

All endpoints use https://<your-domain> as the base URL. The domain can be found in the Marketplace admin panel.

Creating a Service Account

To use the API, create a service account in the admin panel and obtain the Client ID and Client Secret. Refer to the admin panel 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

Header	Required	Description
Content-Type	When using JSON body	application/json (not required for Basic authentication)

Request Body

Parameter	Type	Required	Description
client_id	string	Required	Service account Client ID (issued in admin panel)
client_secret	string	Required	Service account Client Secret (issued in admin panel)

Request Example

curl

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

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": 1800,
  "scope": "openid"
}

note

Marketplace edition does not issue refresh tokens. If the token expires, obtain a new token using the same procedure.

Error Response

Status	Error Code	Description
400	missing_parameters	client_id or client_secret is missing
401	auth_error	Client authentication failed (Client ID / Secret is incorrect)
500	server_error	Server internal error
503	network_error	Communication with the authentication platform failed

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

curl

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

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.

Authorization: Basic base64(client_id:client_secret)

Request Example with Basic Authentication

curl

curl -X POST https://<your-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	Error Code	Description
400	missing_parameters	Required parameters (client_id / client_secret) are missing
401	auth_error	Client authentication failed (Client ID / Secret is incorrect)
500	server_error	Server internal error
503	network_error	Communication with the authentication platform failed