OpenAPI administration

The OpenAPI console runs as its own process and serves each caller a document filtered to the channels that the caller's credentials can invoke - your API consumers get live, accurate documentation without you writing or publishing anything. For the consumer side - signing in, browsing and try-it - share Using the OpenAPI console with them.

The console serves Zato branding by default. To replace it, place files in /opt/hot-deploy/openapi-console/branding/:

There are no configuration keys - the presence of a file is the whole mechanism, and absence of the directory means Zato branding.

Architecture

The console is a separate process on its own port, firewalled independently of the servers. Browsers only ever reach the console - it communicates with the servers over Redis Streams, and no server port is exposed to API consumers. The OpenAPI document itself is built and filtered on the servers: the full document never leaves them, the console receives only the already-filtered version for the signed-in caller and renders it.

The document is rebuilt on the servers when the deployed services or REST channels change - on hot-deploy and on channel create, edit and delete events - and cached in memory, so per-request work is only the per-caller filtering.

The console listens on port 8185 for plain connections and 8186 for SSL, changeable through Zato_Port_OpenAPI_Console and Zato_Port_OpenAPI_Console_SSL. Certificates and SSL options follow the same environment variables as the rest of the platform - see SSL/TLS configuration.

Channel eligibility

A REST channel appears in the OpenAPI document only when it meets all five conditions:

1. It is a REST channel - connection channel, transport plain_http
2. It is active
3. It is not internal
4. It points at a service deployed on the server
5. Its OpenAPI flag is not off - an unset flag means included

The same rules bind everyone, admins included. Inactive channels, internal channels and channels with the flag off are in nobody's document, and the try-it relay refuses them for everyone. Channels created by hand and channels created automatically are documented alike once they pass the checks above.

Only REST channels are documented, never bare services - a deployed service with no channel pointing at it appears in no document.

Every REST channel has an "OpenAPI" checkbox in its create and edit forms in the Dashboard, checked by default. Unchecking the box removes the channel from every document while the channel keeps serving traffic - uncheck it for endpoints that should work but not be advertised.

Per-caller filtering

Callers sign in to the console with existing security definitions - Basic Auth (username and password), API keys (the definition's name as the username, the key as the password) or Bearer tokens (client ID and secret). No new credential type exists for the console.

A caller's document contains only the channels whose security definition is the caller's own, or whose security groups include the caller's definition. The try-it relay enforces the same rules - a channel outside a caller's document cannot be invoked through the console either.

Admins sign in with the same credentials as the Dashboard admin and receive the unfiltered document - all the channels eligible per the rules above - with full try-it access.

Entra ID sign-in

If the Dashboard uses Microsoft Entra ID, the console does too, reading the same Zato_Dashboard_Auth_Type and Zato_Dashboard_Auth_Entra_* variables. Every Entra ID user is an administrator - Zato_Dashboard_Auth_Entra_Group_Admin is the one list that decides who signs in, and its members receive the unfiltered document. The credential-filtered view belongs solely to callers signing in with security definitions.

The only console-specific setting is the redirect URL, since Entra ID requires an exact match per application:

export Zato_OpenAPI_Console_Auth_Entra_Redirect_URL=https://api-console.example.com/openapi/console/login/callback

Everything else comes from the Dashboard's configuration - the app registration in Entra ID gains one more redirect URI.

Auto-created REST channels

The server can create REST channels automatically for deployed services, so exposing a service requires no channel work at all, and every channel created this way appears in the console like any other. For the feature itself - the environment variables, the pattern families and the security posture - see Auto-created REST channels.

Contract diffing

On every rebuild the server compares the new document against the previous one and logs the differences that break existing consumers - removed endpoints, removed fields and type changes. The report appears in the server log as part of the deploy output, one warning per change, prefixed with OpenAPI breaking change:. The report is informational - the deploy itself proceeds - but it makes a contract break visible the moment the change is deployed, not when a consumer's calls start failing.

See also

Learn more