API details and online testing

The API detail page is the entry point for callers to learn about and use a published API. The page provides API documentation, authentication instructions, multi-language calling examples, a signature tool and online testing.

Opening the detail page

There are three ways to open the API detail page:

• Click an API card in API Hub;
• Click "Docs" under API List → Published;
• Visit /doc?aid={apiId}&env={envCode} directly.

env determines which environment's address and parameter snapshot the page displays. API Hub carries prod by default; when entering from the API list, another environment can be specified. If the environment does not exist, or the API is not live in that environment or has been taken offline, the page cannot load the API information.

Page structure

The top of the page is the basic information area, and below it there are only two tabs:

Tab	Content
API docs	Request/response parameters, authentication instructions, calling examples
Online testing	Send calls from the browser directly to the real environment and view the response

The current version has no separate MCP tab. If an API is also published with the MCP protocol, see MCP access for integration; the MCP client configuration is available from "MCP configuration" in the app credential.

Basic information

Information	Description
API name	The API name used at release time
API ID	The ID of the current API source
Authentication	None / AppKey / AppKey + Signature / OAuth2 client credentials / Enterprise IdP JWT
Go-live time	The go-live time of the current environment snapshot
Version	The version in the API's basic information
API address	Current environment address + API path, with one-click copy
API description	The API description at release time

If no access address is configured for the current environment, the API address row shows "No access address configured for the current environment", and online testing is unavailable.

Mock address

When the detail page is in the dev environment and the API has an enabled Mock rule, an additional Mock address row is displayed:

{environment address}/mock/dev{API path}

The Mock address is only open to development integration, and requests must carry a valid X-AppKey. For Mock rules, delay and response configuration, see API testing and Mock.

API docs tab

Request parameters

Parameters are displayed grouped by location, covering the header, query, path and body categories. Each parameter includes its name, type, whether it is required, an example value and a description; object and array parameters are expanded by level.

Response parameters

Response parameters show the field name, type, description and example value. Example values come from the "example value" configuration in the API definition; when it is not configured, a default value is generated by type.

Authentication headers

Different authentication methods require different request headers:

Authentication	Headers	Description
None	None	The API is publicly callable but may still be subject to IP, flow control and other governance rules
AppKey	X-AppKey	Validates app identity only, not the signature
AppKey + Signature	X-AppKey, X-Timestamp, X-Nonce, X-Sign	Uses the SM3 digest and HMAC-SM3 signature by default
OAuth2 client credentials	Authorization	Value is Bearer <access_token>, where the token comes from /oauth2/token
Enterprise IdP JWT	Authorization	Value is Bearer <enterprise_token>, issued by the enterprise IdP; no AppKey or signature is needed

Signature rules:

Signature string = HTTP_METHOD + "_" + API_PATH + "_" + AppKey + "_" + Timestamp + "_" + Nonce + "_" + payload digest
Payload digest = SM3(raw query string + 0x0A + request body)
X-Sign = HMAC-SM3(AppSecret, signature string)

• The query string excludes the leading ? and must match the content actually sent character for character;
• GET and HEAD requests have no body, so the body part of the payload is empty;
• Timestamps are in milliseconds, with an allowed window of 10 minutes;
• A nonce cannot be reused within 10 minutes;
• The default algorithm is SM3; the X-Algorithm: HmacSHA256 header switches to HMAC-SHA256.

For the complete security rules, error codes and signature implementations in multiple languages, see the Signature Authentication Guide.

Online signature tool

For APIs using app_secret authentication, an "Online signature" entry is provided next to the authentication instructions. After entering the AppKey, AppSecret, raw query string and request body, the tool automatically generates the timestamp, nonce, payload digest and X-Sign, which can be copied into debugging tools. The signature tool uses the SM3 algorithm by default.

OAuth2 integration guide

For APIs using oauth2 authentication, the same position shows an "OAuth2 integration guide" explaining how to exchange the app credential for a token:

POST {environment access address}/oauth2/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id={AppKey}&client_secret={AppSecret}

• client_id is the app's AppKey and client_secret is its AppSecret;
• A successful call returns access_token, token_type, expires_in and scope, with a default validity of 30 minutes;
• Calls then carry Authorization: Bearer <access_token> and no longer compute a signature;
• The AppSecret is transmitted only once, when exchanging for the token; always call from the server over HTTPS.

For the complete parameters, errors and multi-language examples, see OAuth2 client credentials authentication.

JWT integration guide

For APIs using jwt authentication, the same position shows a "JWT integration guide" explaining how to call with a token issued by the enterprise IdP:

Authorization: Bearer {enterprise_idp_access_token}

• The token is issued by the enterprise IdP (Keycloak, Azure AD, etc.); the platform only verifies it and provides no token exchange endpoint;
• The request needs only Authorization; no X-AppKey, X-Timestamp, X-Nonce, or X-Sign;
• The caller's credential must bind (IdP, subject) so the platform can identify the app;
• Authentication failures return HTTP 401/403/503 + WWW-Authenticate instead of an HTTP 200 business code.

For complete configuration, claims requirements and multi-language examples, see Enterprise IdP JWT authentication.

Calling examples

The API documentation provides calling examples in six languages: cURL, Java, Go, PHP, Python and JavaScript. The addresses in the examples are taken from the current environment.

Examples do not include signatures or token exchange

The code samples only demonstrate the request structure and parameters; they do not calculate X-Sign or call the token endpoint. APIs with app_secret authentication must implement the signature according to the signature rules themselves, or generate it with the online signature tool above before calling; APIs with oauth2 authentication require exchanging an access_token first and putting it in the Authorization header; APIs with jwt authentication require obtaining a token from the enterprise IdP first.

Online testing tab

Online testing sends fetch requests from the browser directly to the API address, without going through the platform backend proxy.

Steps

1. Fill in the header, query, path and JSON request body in the parameter table;
2. For APIs with app_secret authentication, enter the AppKey and AppSecret; X-Timestamp, X-Nonce and X-Sign are generated automatically on send;
3. For APIs with oauth2 authentication, enter the AppKey and AppSecret and click "Get token", then click "Send";
4. For APIs with jwt authentication, paste the access token issued by the enterprise IdP (kept only in page memory and cleared when switching APIs);
5. Click "Send";
6. View the HTTP status code, response time, response size and response content in the response area.

Behavior

• The page pre-fills parameter rows based on the API parameter definitions, bringing in required fields and default values directly;
• app_key authentication pre-fills the X-AppKey header, and you need to enter the app credential;
• oauth2 authentication exchanges a token at /oauth2/token on the same origin as the API address and writes Authorization: Bearer <access_token> automatically; the token is reused for expires_in - 30 seconds, and a 40025 / 40026 response triggers one automatic re-exchange and retry;
• jwt authentication injects only Authorization: Bearer <enterprise_token> and never injects an AppKey; the response area also shows WWW-Authenticate;
• app_secret authentication regenerates the timestamp and nonce on every send, and the signature is computed from the query and request body actually sent;
• The request body only supports JSON mode; invalid JSON is blocked before sending;
• JSON responses are formatted for display; otherwise the response is shown as text;
• When HTML is returned, a hint is shown, usually indicating that the environment address is misconfigured and the request hit the frontend page.

Common failure causes

Symptom	Possible cause
Prompt to fill in authentication parameters	AppKey or AppSecret is missing for an app_secret / oauth2 API, or the token is missing for a jwt API
Token exchange fails with invalid_client	The AppKey/AppSecret do not belong to the same app, the app is disabled, or the source IP is not in the app whitelist
Browser cross-origin error	The target environment does not allow the current site across origins, or the gateway CORS configuration does not cover that origin
Mixed content blocked	The docs site is HTTPS while the environment address is HTTP
HTML returned	The environment access address is not configured or is configured as the frontend site
401 / 40013	Invalid credential, wrong signature, or timestamp or nonce validation failure
40024 / 40025	An oauth2 API call has no Bearer token, or the token is expired or invalid
401 / 40029 (jwt)	The enterprise IdP token is invalid, expired, has the wrong audience, or fails signature verification
403 / 40031 (jwt)	The token subject is not bound to any app, or the binding does not match
503 / 40030 (jwt)	JWT is not enabled, or the IdP / JWKS is temporarily unavailable
403 / 40018	The request source IP is not in the app whitelist
429 / 40023	The subscription's daily call quota is exhausted

Subscription entry

APIs that require authorization show a "Subscription request" button at the top of the page:

• APIs without authentication do not show the application button;
• When an application is already under approval, the button shows "Under approval" and is disabled;
• Once the application is approved, the app credential can call the API.

For the application fields and approval process, see Subscriptions and approval.

Related documentation

• API catalog and access applications
• App credentials and authorization
• Subscriptions and approval
• Signature Authentication Guide
• OAuth2 client credentials authentication
• Enterprise IdP JWT authentication
• MCP access