Skip to main content

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

Marketplace
https://<auth-domain>

Authentication Endpoint List​

Marketplace

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

MethodEndpointDescription
POST/api/v1/oauth/tokenToken endpoint in the standard form (RFC 6749). Issues an access token via the Client Credentials flow.
POST/api/v1/auth/external-service-tokenThe earlier token endpoint. Issues an access token via the Client Credentials flow.
GET/.well-known/jwks.jsonJWKS 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).

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

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_typestring必須Specify client_credentials
client_idstring—Specify this when authenticating the client in the body (`client_secret_post`)
client_secretstring—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)
1curl -X POST https://<auth-domain>/api/v1/oauth/token \
2-u "your_client_id:your_client_secret" \
3-H "Content-Type: application/x-www-form-urlencoded" \
4-d "grant_type=client_credentials"

Response Fields (200 OK)​

FieldTypeDescription
access_tokenstringAccess token in JWT format
token_typestringBearer
expires_innumberAccess token expiration time (seconds)
scopestringGranted scopes (space-separated; omitted when there are none)

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

Error Response​

StatuscodeDescription
400invalid_requestThe client authentication was sent with both methods, or the client_id in Basic authentication differs from the client_id in the body
401invalid_clientThere is no client authentication, or the Client ID / Secret is incorrect (with a WWW-Authenticate header)
429rate_limit_exceededToo 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
500server_errorThe 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.

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_idstring必須Client ID of the service account (issued in the admin console)
client_secretstring必須Client Secret of the service account (issued in the admin console)

Request Example​

Get token (service account)
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}'

Response Fields (200 OK)​

FieldTypeDescription
successbooleanRequest success (true on success)
access_tokenstringAccess token in JWT format
token_typestringBearer
expires_innumberAccess token expiration time (seconds)
scopestringGranted 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​

StatuscodeDescription
400missing_parametersclient_id or client_secret is missing
401auth_errorClient authentication failed (Client ID / Secret is incorrect)
429rate_limit_exceededToo many requests from the same source. Retry later (if a Retry-After header is present, wait that many seconds)
500server_errorServer 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
1curl https://<auth-domain>/.well-known/jwks.json

Response Fields (200 OK)​

FieldTypeDescription
keysarrayArray of JWK (JSON Web Key) objects
keys[].kidstringKey ID. Match against the kid in the JWT header to identify the verification key
keys[].ktystringKey type (e.g., "RSA")
keys[].algstringAlgorithm (e.g., "RS256")
keys[].usestringKey usage. "sig" (signature verification)
keys[].nstringRSA public key modulus (Base64url encoded)
keys[].estringRSA public key exponent (Base64url encoded)

Response Headers​

HeaderDescription
Cache-Controlpublic, 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). 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).

MethodEndpointDescription
GET/realms/<realm>/.well-known/openid-configurationDiscovery 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/authAuthorization endpoint
POST/realms/<realm>/protocol/openid-connect/tokenToken endpoint (exchanging authorization codes and refreshing with refresh tokens)
GET/realms/<realm>/protocol/openid-connect/certsPublic keys for verifying signatures (JWKS)
GET/realms/<realm>/protocol/openid-connect/userinfoUser information
GET/realms/<realm>/protocol/openid-connect/logoutSign-out
POST/realms/<realm>/protocol/openid-connect/revokeToken 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

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​

ClaimTypeDescription
substringService account ID (UUID)
issstringIssuer URL. It is the internal address of the authorization server (http://<internal-authorization-server-address>/realms/<realm>)
audstringFixed value "account"
expnumberExpiration time (Unix timestamp)
iatnumberIssued at (Unix timestamp)
jtistringJWT ID. Unique identifier for the token
typstringToken type ("Bearer")
azpstringAuthorized Party (Client ID that requested the token)
scopestringGranted scopes (space-separated)
acrstringAuthentication 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.

ClaimTypeDescription
emailstringInternal identifier assigned by the authentication platform
email_verifiedbooleanInternal flag assigned by the authentication platform (always true)
preferred_usernamestringInternal identifier assigned by the authentication platform

Service Account Information​

ClaimTypeDescription
client_idstringClient ID
clientHoststringRequest source host
clientAddressstringRequest source IP address

Roles​

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

ClaimTypeDescription
realm_access.rolesstring[]List of realm-level roles assigned by the authentication platform
resource_access.account.rolesstring[]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"}

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://<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.

Error Response Format​

FieldTypeDescription
successbooleanAlways false
errorstringError message
messagestringError message (same as error)
codestringError 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​

StatuscodeDescription
400missing_parametersRequired parameters (client_id / client_secret) are missing
401auth_errorClient authentication failed (Client ID / Secret is incorrect)
429rate_limit_exceededToo many requests from the same source. Retry later (if a Retry-After header is present, wait that many seconds)
500server_errorServer internal error (including when the authentication platform cannot be reached)