Overview and quick start

Read the full manual · Download the full PDF · Overview PDF

2026.10 · Applies to Capability Center and the gateway call APIs. For administration, see the Zentrix Gateway Admin Console Guide. For the complete description, see the Zentrix Gateway User Manual.

1. Product scope and entry points

Zentrix Gateway unifies model and tool access inside the enterprise and enforces authentication, quotas, routing, guardrails, and audit on the gateway. It can be deployed in the customer environment or hosted as SaaS by the service provider. Hosting region, plan, and service level follow the service agreement. External dependencies such as model providers, identity sources, and notification channels are configured by the customer.

The platform has two surfaces:

Capability Center tabs are listed below. Catalog pages can be opened without signing in:

Which catalog entries appear is decided by the administrator's publish settings. Whether you can call them is decided by Available scope and its validity period. Seeing an entry does not mean you already have permission. MCP and API services you are not authorized to use show An administrator needs to distribute this. Admin Console in the account menu at the top right appears only for accounts that can see at least one admin menu.

2. Choose a model

1. Open Models. Use Search models to search by name, or filter on the left by Categories and Model Providers, and sort by Latest or Most Used. After sign-in, the list shows only models the current account can use.
2. Open a card for model details. The page header shows the provider, context, modality, user billing price, and listing time.
3. When needed, choose Open in Playground to try a chat model. Trials are real calls with real charges, recorded in usage as a playground run.

3. Get and manage API keys

Each API key is bound to one model group and can call every enabled model in that group. Usage is billed to the API key affiliation chosen at creation. Upstream provider keys are maintained by administrators. Business systems use only gateway API keys.

• Options for API key affiliation come from administrator distribution, such as public, department, functional group, or personal. When only one affiliation is available, it is selected automatically.
• Custom API key (optional) imports a key a business system already uses. It must be 32–512 characters and contain only letters, digits, and -._~+/=. Leave it empty to generate one.
• Save the key into the business system's secret store immediately. Do not put it in screenshots, chat logs, or a code repository.
• When the tenant turns off token access in the security policy, API keys cannot be issued. The page tells you to contact an administrator.

For a key that is no longer used or may have leaked, choose Revoke on Home → API keys. Calls that use that key fail immediately. Members cannot rotate keys. To keep call continuity, ask an administrator to Rotate key in API key management. The old key stays usable during the grace period. See chapters 8 and 9 of the Zentrix Gateway User Manual.

4. Make the first call

The Base URL is the gateway's public access URL plus a fixed prefix. Make your first API call on the model details page copies the address for the current environment. In the table below, <gateway-url> is that access URL:

1. In Make your first API call, choose a protocol (OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, Gemini generateContent) and a language (TypeScript, Python, cURL).
2. Put the model name returned by Models or List available models (GET /models) in the request. If the model is not in the model group bound to this key, the call returns 404.
3. Inject the key into the runtime. Send a minimal request first and check the response shape and the x-request-id response header. Then verify streaming, tool calls, images, and other features you actually use.
4. Do not send two credentials with different values on the same request. That returns 400.

Developer tools use these environment variables by protocol:

Chat APIs convert automatically among the four protocols. A caller can use any protocol against any chat model. Embeddings, rerank, image, speech, and batch judgment are provided only in OpenAI-compatible form. During streaming the gateway sends a heartbeat every 15 seconds. Idle timeouts on intermediate proxies must be greater than 15 seconds. For the API list, request-body limits, and session-attribution headers, see chapter 10 of the Zentrix Gateway User Manual.

A successful trial in the browser does not mean the business server can reach the gateway. DNS, proxy, TLS, and egress on the business side need a separate check. Copied samples may already include a key created in this session. Remove credentials before sharing.

5. Use MCP tools and API services

MCP services:

1. Open MCP, open the service details, and read the tool descriptions and data boundary.
2. In Service configuration, choose Get connection settings. When the service requires personal credentials, first choose Create app credential and fill in personal credentials, or choose Complete authorization and finish OAuth with a personal external account.
3. In Validity, choose a validity period, then choose Confirm token issuance. Options include the tenant default, 24 hours, 48 hours, 7 days, 30 days, and custom, all capped by the tenant's maximum allowed validity. Administrators can set Maximum token validity under Global settings → Account & session security → Security policy → External access to at most 720 hours (30 days), or choose Never expires. After never-expires is allowed, the issue UI for MCP, HTTP API, and A2A services can choose Never expires. Those tokens have no expiry and can still be revoked.
4. Copy the Streamable HTTP URL or JSON configuration as the client requires. The token is shown once. It represents the current member identity and is for personal use only.
5. When the tenant has OAuth enabled, you can also choose Show MCP configuration and let the MCP client complete sign-in. The authorization page lists the callback URL and access scope. Check them, then choose Allow access.
6. Verify with one clearly scoped read-only call.

Whether a tool can be called is also limited by traffic rules the administrator sets for MCP tools. Calls that hit a deny rule are rejected.

API services: Open the service details on APIs and choose Generate token to issue a short-lived access token. The panel gives the proxy URL, request path, request body, access token, and a curl example. The call URL looks like <gateway-url>/api/v1/agent-gateway/proxy/<service-id>/<upstream-path>, with header Authorization: Bearer <access token>. When you no longer need it, choose Revoke token.

See chapter 11 of the Zentrix Gateway User Manual.

6. Skills, plugins, and external agents

Only members inside the available scope can see and use these entries. See chapter 12 of the Zentrix Gateway User Manual.

7. Errors and limits

The gateway returns errors in the protocol the caller used. Business systems should handle the reason in the error body and must not parse message text. Response header x-should-retry says whether a retry might change the result. When a retry is possible, Retry-After may be present.

The same HTTP status can come from different layers. For example, 503 may be a circuit breaker or upstream overload. Use reason. Quotas reset on UTC calendar periods. “Today” starts at 08:00 Beijing time. For the full error catalog, see section 10.8 of the Zentrix Gateway User Manual.

8. Check records and report problems

Members view their own data in the Usage group on the left of Home:

• Usage: call count, message count, cumulative tokens, and activity for the last 180 days;
• Model Usage: consumption by API key, model group, model, and billing affiliation;
• Call Logs: inspect model and MCP calls one by one, search by Request ID, and choose Export records to download CSV. Calls without a price show “cost missing”.

When a record is missing, check the time range, the key and model group that were used, and whether the request bypassed the gateway and went upstream directly.

When you report a problem to an administrator, provide the time and time zone, model or tool name, protocol and client, reason and the prompt text, the Request ID from Call Logs (the same value as response header x-request-id), and whether it reproduces. Do not send full keys, tokens, or unrelated business content.

9. First-time administrator rollout

1. On System Settings → Global settings → License, confirm which modules are enabled. In Organization & Access, create departments, functional groups, and members. In Role Management, assign Config Admin, Security Admin, and Auditor.
2. Onboard and verify upstreams in Model Providers. In Models, confirm each model has an enabled upstream. Add models to Organization & Access → Model Groups, and in Visibility & quotas authorize only a pilot scope first.
3. Onboard MCP Services, API services, External agent, Skills, and Plugins as needed. After publishing, set available scope.
4. When model guardrails and dynamic routing are enabled, configure detection and routing in Guardrails and Traffic rules, and use Validate rule to check match order.
5. Have a pilot member complete success, permission-denied, and quota-exhausted cases with their own API key. Check results on the Requests tab of Overview and in Operation Audit, then widen the scope.

For the full procedure, see the Zentrix Gateway Admin Console Guide and chapter 1 of the Zentrix Gateway User Manual. For traffic-rule fields and defaults, see the Zentrix Gateway Traffic Rules User Manual.