Authentication Reference (Marketplace)

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

Marketplace 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 access token via Client Credentials flow.
GET	/.well-known/jwks.json	JWKS endpoint. Returns JSON Web 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

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

Request Headers

Header	Required	Description
Content-Type	Required	application/json

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	code	Description
400	missing_parameters	client_id or client_secret is missing
401	invalid_credentials	Client authentication failed (Client ID / Secret is incorrect)
500	server_error	Server internal error

Error Response Example

JSON

{
  "success": false,
  "error": "Authentication information is incorrect",
  "message": "Authentication information is incorrect",
  "code": "invalid_credentials"
}

JWKS Endpoint

GET /.well-known/jwks.json

Return a JSON Web Key Set (JWKS) for JWT signature verification. Use this to verify access token signatures.

Request Example

curl

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

Response Headers

Header	Description
Cache-Control	public, max-age=3600

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. Claims are output in flat structure.

Standard Claims

Claim	Type	Description
sub	string	Service account ID (UUID)
iss	string	Issuer URL
aud	string	Audience (Client ID)
exp	number	Expiration time (Unix timestamp)
iat	number	Issued at (Unix timestamp)
azp	string	Authorized Party (Client ID that requested the token)
scope	string	Granted scopes (space-separated)
acr	string	Authentication Context Class

User Information

Claim	Type	Description
email	string	Service account email address
email_verified	boolean	Whether email address is verified
preferred_username	string	Username

Profile (Optional)

Only output if user attributes are set for the service account in the admin panel.

Claim	Type	Description
organization	string	Organization
job	string	Job title
bio	string	Bio

Service Account Information

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

Roles

Claim	Type	Description
realm_access.roles	string[]	Assigned roles (e.g., user)

JWT Access Token Payload Example

JSON

{
  "sub": "7c6f8a3c-2e1b-4d9f-a5e2-1b4c8d3f2e1a",
  "iss": "https://your-domain/auth",
  "aud": "account",
  "exp": 1678886400,
  "iat": 1678884600,
  "azp": "my-service-account",
  "acr": "1",
  "scope": "openid email profile",
  "email": "service@example.com",
  "email_verified": true,
  "preferred_username": "service-account-my-service",
  "client_id": "my-service-account",
  "clientHost": "192.168.1.100",
  "clientAddress": "192.168.1.100",
  "realm_access": {
    "roles": ["user"]
  }
}

Client Authentication

At the token endpoint, perform client authentication using one of the following methods.

JSON Body

Include client_id and client_secret in 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

code	Status	Description
missing_parameters	400	Required parameters (client_id / client_secret) are missing
invalid_credentials	401	Client authentication failed (Client ID / Secret is incorrect)
rate_limit_exceeded	429	Request rate limit exceeded
server_error	500	Server internal error