App credentials and authorization

Callers access protected APIs through app credentials. A credential contains an AppKey and an AppSecret; it can be set up as a project-level pass or authorized API by API.

Entry point

After signing in, go to Account Center → App Credentials. The list is isolated by the current project and shows only credentials created in this project.

Credential list

Column	Description
ID	Credential ID
Name	App name; click to view details
AppKey	The app identifier used when calling
Scope	API-level (api) or project-level (project)
IP restriction	Whether an IP whitelist is configured
Created by	The credential creator
Last modified	The most recent update time
Actions	MCP configuration, authorization list, edit, delete

Credential enable/disable is retained in the backend API; the current list does not expose a toggle.

Actions

• MCP configuration: available only when the credential has MCP enabled; the dialog provides MCP client JSON that can be copied directly;
• Authorization list: view and revoke the API authorizations held by this credential;
• Edit: modify the name, AppKey, AppSecret, scope, IP whitelist, MCP switch and remarks;
• Delete: deleting a credential also removes its authorization relationships, and calls using that credential fail immediately.

Creating a credential

Field	Required	Description
Name	Yes	App name, up to 25 characters; spaces are removed automatically as you type
AppCode	Yes	App code, which cannot be modified after creation; the rule is ^[a-zA-Z][a-zA-Z0-9]{4,24}$, that is, starting with a letter and 5–25 letters or digits
AppKey	Yes	Generates ak_ plus a 32-character random string by default; can be edited manually or regenerated
AppSecret	Yes	Generates a 32-character random string by default; can be edited manually or regenerated
Scope	Yes	api or project, see below
IP whitelist	No	Separate multiple IPs with English commas; the range startIP~endIP is also supported
Enable MCP	No	When checked, the credential can access MCP services through /mcp/{appCode}
Remarks	No	Usage description

AppCode uniqueness is checked when the input loses focus; even if a duplicate is only warned about, a uniqueness check is still performed by the backend on save. AppCode cannot be edited when modifying a credential.

Keep the AppSecret safe

The AppSecret is visible only when creating or editing a credential. Deliver it to callers through a secure channel. If it leaks, regenerate it in the edit dialog immediately and update the caller's configuration accordingly.

Scopes

Scope	Authorization range	Call validation
API-level api	Only the APIs in the authorization list	Validates API authorization, API authentication method and IP whitelist
Project-level project	All live APIs in the current project	Passed through directly within the project; API-level authorization, API authentication method and IP whitelist are not validated

A project-level credential is effectively a pass within the project and suits internal service-to-service calls. It bypasses the API's own signature validation, so the issuance scope must be strictly controlled; use API-level credentials for external partners.

MCP differences

When calling through /mcp/{appCode}, regardless of whether the scope is api or project, the gateway validates the credential's IP whitelist, the mcpEnabled switch and the AppCode in the path. API-level credentials expose only authorized MCP APIs, while project-level credentials expose all production APIs in the project that are published as MCP.

API authorization

There are three sources of API authorization:

1. The caller submits a subscription application on the API detail page, and authorization is granted automatically after approval;
2. The API owner grants authorization directly in API List → Authorization;
3. Project-level credentials do not require per-API authorization.

In the credential's "Authorization list", you can view the authorized API code, API name, authorization time and authorizer, and click "Revoke authorization" to remove an entry. After revocation, calls from that credential to the API are rejected immediately.

IP whitelist

The IP whitelist restricts call origins:

• Separate multiple entries with English commas, for example 10.0.0.1,10.0.0.2;
• Range notation such as 10.0.0.1~10.0.0.100 is supported;
• The frontend form validates IPv4, while the backend also supports CIDR ranges;
• API-level credentials validate the source IP for both REST and MCP calls;
• Project-level credentials do not validate IP for REST calls but still validate it at the MCP entry.

When the source IP is not in the whitelist, HTTP 200 is returned with the business code 40018.

MCP configuration

After MCP is enabled for a credential, click "MCP configuration" to see the client configuration:

{
  "mcpServers": {
    "ApiGo-MCP": {
      "type": "http",
      "url": "https://www.apigo.cn/mcp/{appCode}",
      "headers": {
        "X-AppKey": "{AppKey}"
      }
    }
  }
}

• {appCode} in url is automatically replaced with the credential's AppCode;
• Placeholders in headers must be replaced with the actual AppKey;
• The dialog shows the default address of the SaaS site; for private deployments, replace it with the actual gateway domain;
• MCP calls only need X-AppKey, not X-Sign; an OAuth2 token (Authorization: Bearer <access_token>) also works, see below.

For protocol details and tool exposure rules, see MCP access.

OAuth2 integration

The same credential can also act as an OAuth2 client credential (choose "OAuth2 client credentials" as the API authentication method):

• client_id is the credential's AppKey and client_secret is the AppSecret; no extra key is needed;
• The token endpoint is POST /oauth2/token on the same origin as the gateway, with grant_type=client_credentials and a default validity of 30 minutes;
• Calls to APIs or MCP carry Authorization: Bearer <access_token> and skip the signature computation;
• The "OAuth2 integration" row in the credential editing dialog shows the token endpoint, so it can be copied and handed to callers;
• Disabling or deleting the credential invalidates the token immediately; after rotating the AppSecret, a new token must be exchanged.

Typical fit: the caller is a standard OAuth2 client, an agent or a backend service that cannot easily implement the SM3 signature algorithm. For external partners, still use API-level credentials with an IP whitelist.

For the complete exchange flow, error codes and multi-language examples, see OAuth2 client credentials authentication.

Enterprise IdP JWT integration

If your organization already standardizes on Keycloak, Azure AD, or another IdP, the platform can verify JWT tokens issued by that IdP instead of issuing its own:

• The credential must bind (jwt_idp, jwt_subject) so the gateway can map the JWT subject to an app;
• Configure the binding in the JWT identity binding section of the credential dialog; IdP and subject must both be filled in or both be cleared;
• Within a project, one subject can bind to only one app;
• Callers send Authorization: Bearer <enterprise_token> and need no AppKey, AppSecret, or signature;
• Authentication failures return HTTP 401/403/503 + WWW-Authenticate, unlike the HTTP 200 contract of platform OAuth2;
• JWT is not yet supported at the MCP entry point; it will be enabled in phase 2.

For configuration, claims requirements and the full call flow, see Enterprise IdP JWT authentication.

Relationship between credentials and subscriptions

• API-level credentials: obtain API authorization first (subscription approval or owner authorization), then are bound by the subscription's daily call volume and validity period;
• Project-level credentials: no per-API subscription is needed; they access APIs in the project directly, but are still subject to API governance rules (flow control, circuit breaking, IP rules, WAF, etc.);
• After a credential is deleted or disabled, its related subscriptions and MCP access become invalid at the same time.

Security recommendations

• Use a different credential for each caller to avoid sharing;
• Prefer API-level credentials and use project-level credentials only when truly necessary;
• Configure an IP whitelist for production calls;
• Rotate the AppSecret regularly and notify callers promptly after rotation;
• Never store the AppSecret in plaintext in code repositories, frontend code or logs.

Related documentation

• Subscriptions and approval
• API details and online testing
• MCP access
• Signature Authentication Guide
• OAuth2 client credentials authentication
• Enterprise IdP JWT authentication