# OpenAPI administration

Run the OpenAPI console and decide which channels each API consumer sees.

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](https://zato.io/docs/dev/rest/openapi-console.html) with them.

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

| File | Effect |
| --- | --- |
| `logo.svg` | Replaces the logo |
| `favicon.svg` | Replaces the favicon |
| `custom.css` | Injected last, on top of the console's own styles |
| `title.txt` | Replaces the page title |

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

## Architecture {#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](https://zato.io/docs/admin/security/ssl/index.html).

## Channel eligibility {#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.

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 {#per-caller-filtering}

Callers sign in to the console with existing security definitions - [Basic Auth](https://zato.io/docs/security/basic-auth.html) (username and password), [API keys](https://zato.io/docs/security/api-keys.html) (the definition's name as the username, the key as the password) or [Bearer tokens](https://zato.io/docs/security/bearer-tokens/index.html) (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](https://zato.io/docs/security/groups.html) 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 {#entra-id-sign-in}

If the Dashboard uses [Microsoft Entra ID](https://zato.io/docs/admin/dashboard-auth.html), 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 only list that determines who can sign 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:

```bash
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.

## Contract diffing {#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 at deployment time, before any consumer's calls start failing.

## See also {#see-also}

- [Using the OpenAPI console](https://zato.io/docs/dev/rest/openapi-console.html) - Signing in, browsing and try-it, for API consumers
- [OpenAPI specifications](https://zato.io/docs/dev/rest/openapi.html) - Downloadable YAML files grouped from selected REST channels

## Learn more {#learn-more}

- [REST integration overview](https://zato.io/integrations/rest/) - Start here to see how teams build REST integrations
- [In-depth API tutorial](https://zato.io/tutorials/main/01.html) - Master architectural patterns for production-ready integrations
- [Modern REST API tutorial](https://zato.io/tutorials/rest-api/python.html) - Design, build and secure REST APIs with Python