API Gateway administrator guide

Configure, govern, deploy, and monitor APIs through the API Gateway Admin Console.

The Admin Console (http://localhost:5173 locally) is where platform admins configure environments, publish and govern APIs, manage traffic policies and certificates, run canary/blue-green rollouts, and monitor the gateway. This guide covers every tab in the console.

All actions require an Admin Token (see Getting Started). Most actions additionally require that your token’s role grants access to the specific environment you’re acting on — see Permissions below.

Console layout

The top bar (config bar) holds the Control Plane URL, an optional Sign in with SSO field (shown only when no token is set), and the Admin Token field itself, with a Sign Out button to clear it.

Below that, tabs are grouped into three categories in the navigation:

Configuration: Setup, Env Setup, Wizard, APIs, Policies
Management: Lifecycle, Production Approvals, Portal Approvals, Operations
Monitoring: Dashboard, Reports, Certificates, System Settings, Canary Deployments, AI Recommendations

Permissions

The backend enforces two authorization checks on nearly every action. Understanding them explains why an action that works for one admin may be rejected for another.

Global admin

Holding the exact role admin makes you a global admin. Global admin is required for:

Creating and listing environments (Env Setup / Wizard’s environment-creation step)
Managing admin users and identity providers
SSO Admin Authentication configuration (System Settings)
Approving canary auto-promotion checks
Publishing to an environment that has “requires approval” turned on (see below)
A handful of single-resource lookups/deletes that aren’t scoped to a specific environment in their request (e.g. deleting a route or upstream directly by ID, fetching a single API/route/upstream by ID)

Environment-scoped admin

Access to a specific environment is granted via a role of the exact form env:<environment-id>:admin. An admin can hold this role for one, several, or all environments. Holding it (or being a global admin) is required for almost everything else: creating/reading upstreams, APIs, versions, routes, certificates, canary and blue-green deployments, traffic/auth/resilience policies, applications, credentials, configuration versions, and publish/activate/rollback/reconcile operations — as long as the target belongs to an environment you have access to.

Practical effect: an environment-scoped admin can fully manage the environments they’ve been granted, but cannot create new environments, cannot touch SSO or admin-user configuration, and cannot bypass an approval gate.

Approval-gated environments

An environment can be flagged “requires approval.” When it is, only a global admin may publish, activate a configuration version, roll back, or reconcile that environment — an environment-scoped admin’s attempt is rejected with a message to the effect of “publishing to this environment requires an approved change record; use a global admin to bypass.” This is separate from the Production Approvals tab (which gates API version lifecycle transitions into published, not configuration publish operations) — see Production Approvals below.

Admin authentication

The console does not accept a static shared secret. The Admin Token is a signed JWT (RS256), verified by the control plane against a JWKS endpoint, and must carry the right role claim. Tokens are obtained either by pasting one directly (local dev — see Getting Started) or via Sign in with SSO, which redirects to your organization’s identity provider and returns you to the console already signed in.

Setup tab — Quick Publish

Goal: Create a complete, working API path (environment, API, version, route, policies, activation) in a single form and one click.

Starting state: You have an admin token. You don’t need any existing resources — Quick Publish creates everything from scratch, including a new environment.

Steps:

Go to the Setup tab.
Fill in Environment key, Environment name, API name, API slug, API version, Route path, Target host, and Target port (the backend the route proxies to).
Choose Auth mode: API key (creates an application + key and attaches an auth policy) or None.
If API key auth is selected, fill in Application name and Application owner.
Configure Traffic & Resilience: traffic scope (Client IP or Application), rate limit (RPS/burst), required headers/query params, and connect timeout.
Click Create and Activate.

Expected outcome: The console creates, in order: environment → upstream → API → API version → route → (if API key auth) application + API key + auth policy → traffic policy → resilience policy → configuration version → activation. Each step posts a ✓ status line as it completes, and if API key auth was used the new key is shown once in a highlighted banner — copy it immediately, as it is not retrievable again. On any failure, the banner shows the error and the resources created up to that point remain (nothing is auto-rolled-back client-side).

Env Setup tab — guided environment wizard

Goal: Stand up a new environment with its first upstream and optional API-key security, via a guided 4-step wizard (useful when you want more control than Quick Publish’s flat form, without yet defining an API).

Steps: Create Env (key + name) → Add Upstream (name, host, port, scheme) → Configure Security (optionally check “Generate API key,” and optionally pick a JWT provider: Auth0, Okta, Keycloak, or Custom) → Review & Finish, then click Finish Setup.

Expected outcome: Environment and upstream are created; if API-key generation was checked, an application and key are also created and the key is shown once. A completion screen offers Start New to run the wizard again.

Wizard tab — guided end-to-end publish

Goal: Same end result as Quick Publish (environment → API → version → route → policies → activation) but walked step by step, useful for first-time users or training.

Steps: Fill in environment key/name, API name/slug/version, route path/methods/upstream target, auth mode, rate limit, and CORS across the wizard’s steps, then submit on the final step.

Expected outcome: A Publishing Complete screen lists every resource ID created (environment, upstream, API, version, route).

APIs tab

Goal: Discover what already exists in the system (not just what you created this session) and manage configuration versions.

Browse APIs

Load every environment your token has access to, pick one, and drill down: environment → APIs (name, slug, lifecycle status) → versions (version string, lifecycle status) → routes (name, path, methods). This is read-only and is the way to find resources created in a previous session or by another admin — the console does not persist a global resource list client-side.

Configuration Versions

Enter an Environment ID and click List Config Versions to see every version and its status, with an Activate action per row. Get Detail shows the full JSON snapshot for a specific configuration version ID, plus two safety actions:

Simulate — runs the configuration’s routes through the router logic without touching APISIX, returning what each route would resolve to.
Preflight — validates the configuration before activation and reports pass/fail with specific issues, so you can catch problems before they affect traffic.

Tip: Run Preflight before Activate on anything you didn’t just create yourself with Quick Publish/Wizard (which activate automatically).

Policies tab

Goal: Attach and manage traffic/auth policies on routes, independent of the publish wizards.

Route Auth Policy — set a route’s auth type (API key or None) by Route ID.
Policy Templates — create a reusable, named JSON policy configuration (route_traffic type) that can be applied across routes/APIs/environments, with a Config (JSON) editor.
API Key Expiry — set or clear a credential’s expiration date by Credential ID.
Policy Creation Wizard (bottom of tab) — a guided flow: choose a policy type (rate limit, CORS, IP restriction, request validation, header transform, cache), fill in type-specific fields, pick a target route, and finish. Supports rate limiting, CORS, IP allow/block lists, request validation, header/path/query transforms, response overrides, and response caching (TTL).

Expected outcome: A ✓ Policy applied successfully! confirmation and the policy takes effect on the next configuration activation for that route’s environment.

Lifecycle tab

This tab bundles several distinct release-management tools:

OpenAPI Import

Goal: Bootstrap an API and its routes from an existing OpenAPI 3.x spec instead of defining routes by hand. Steps: Provide an Environment ID, optionally an Upstream ID, paste the OpenAPI JSON, click Import OpenAPI. Outcome: An API (and its routes, derived from the spec’s paths) is created with public catalog visibility.

Promotion

Goal: Move a known-good configuration from one environment to another (e.g. staging → production). Steps: Provide source and target Environment IDs and a source Configuration Version ID, click Promote. Outcome: The named configuration version is replicated into the target environment; the resulting status is shown (e.g. succeeded).

Reconcile Environment

Goal: Detect and correct drift between the control plane’s desired state and what’s actually running in APISIX for an environment. Steps: Enter an Environment ID, click Reconcile. Outcome: A reconciliation status is returned; use this after any manual/out-of-band change to APISIX, or if you suspect the gateway and control plane have diverged.

Canary Deployments (within Lifecycle)

Goal: Gradually shift traffic to a new API version while watching for problems, with an automatic rollback-safe traffic control. Starting state: You need the target API’s ID, the new version’s ID and version string, and the upstream ID it should route to. Steps: Fill in Canary API ID, API Version ID, Version, Upstream ID, and Traffic % (1–100), click Create Canary. Use List Canary to refresh. Each listed deployment has an inline Traffic number input (adjust and it applies immediately) and a Delete Canary button. Outcome: A canary deployment record is created; only one active canary per API version is allowed at a time — creating a second for the same version is rejected. Traffic updates that fail to publish to APISIX are automatically rolled back to the last known-good percentage. Tip — Auto-promotion: Canary deployments can carry auto_promote plus latency/error-rate thresholds. Auto-promotion is fail-closed: if recent metrics for the environment are missing, the canary is left alone rather than promoted — it is never promoted “by default” on missing data. Checking/triggering auto-promotion requires a global admin.

Blue-Green Deployments (within Lifecycle)

Goal: An all-or-nothing, instantly-reversible cutover between two API versions (“blue” = current, “green” = candidate). Steps: Fill in BG API ID, Blue Version ID, Green Version ID, click Create BG. On an active deployment, click Promote BG to cut 100% of traffic to green, or Rollback BG to send it back to blue. Once promoted, only Rollback BG remains available. Outcome: Traffic instantly follows the promoted version. If the underlying APISIX publish fails partway through promote/rollback, the system compensates by restoring the prior traffic split rather than leaving it half-switched. Only one active blue-green deployment per API is allowed at a time.

Canary Deployments tab (standalone)

A second, simpler entry point to create canary and blue-green deployments (same underlying actions as the Lifecycle tab’s cards) without needing to navigate through Lifecycle — useful when you just want to kick off a rollout and already know the IDs involved.

Production Approvals tab

Goal: Approve an API version for production, moving it from review to published lifecycle status.

Starting state: An API version must already be in review status. The complete lifecycle is draft → review → published → deprecated → retired.

Steps: Select the API and API Version from the dropdowns (populated from what you’ve created this session — for versions created elsewhere, look them up via the APIs tab first), click Approve Publish.

Outcome: The version’s lifecycle status transitions to published. This tab governs the API version’s release state, not whether an environment’s configuration is allowed to be activated — those are two separate gates (see Approval-gated environments above).

Portal Approvals tab

Goal: Review and act on developer access requests submitted through the Developer Portal.

Steps: Optionally filter by Status filter (All / Pending / Approved / Rejected), click Load Requests. Each pending request shows Approve and Reject actions.

Outcome: Approving a request lets the requesting developer create an API credential for that application against that catalog entry. Note that access requests against a publicly visible catalog entry are auto-approved by the backend at request time — this tab is primarily for requests against private/restricted catalog entries that need a human decision.

Operations tab

A monitoring dashboard, all scoped by Environment ID:

Platform Overview — request count, error rate (color-coded green <1%, yellow <5%, red ≥5%), P95 latency (with a 100ms visual threshold), auth failures, rate-limit events, and cache hit rate, over the last 60 minutes.
Status Code Distribution — a bar chart of 2xx/3xx/4xx/5xx share of traffic.
Top Consumers — request volume by consumer, useful for spotting abuse or a noisy top client.
Publish Operations — recent publish/activate/rollback/reconcile operations with status and any error message.
Active Alerts — currently firing or pending alerts (e.g. error-rate or latency threshold breaches), each showing the observed value against its threshold.
Report Runs — history of scheduled/on-demand report executions.

Dashboard tab

A higher-level, environment-agnostic view of platform health: total requests, error rate, P95 latency, active alert count, cache hit rate, consumer breakdown, and status-family breakdown, over a configurable time window.

Reports tab

Create Report Schedule — recurring runtime-usage reports (weekly cadence) for an environment, delivered to a comma-separated recipient list.
Generate Report Now — a one-time runtime-usage report for an environment, generated immediately.
Report Runs — history of both scheduled and on-demand runs.

Certificates tab

Goal: Upload and manage TLS server certificates that APISIX presents for SNI-based hostnames.

Create Certificate

Provide Environment ID, SNI / Domain (hostname), Certificate (PEM), and Private Key (PEM), click Create Certificate.

Validation to know about: the backend parses the certificate and requires the SNI to match (case-insensitively) either a DNS Subject Alternative Name or the certificate’s Subject Common Name — a mismatch is rejected with an explicit “SNI does not match certificate subject or SAN” error. It also rejects already-expired certificates and private keys that don’t match the certificate’s public key. Only one active certificate per (environment, SNI) pair is allowed at a time.

List Certificates

Enter an Environment ID to list its certificates, with a rotate action per certificate (uploads a replacement while keeping the same SNI).

Certificate Upload Wizard

A guided alternative: paste the certificate PEM, paste the private key PEM, add one or more SNI domains, review, and finish — with inline validation catching an obviously malformed PEM (missing -----BEGIN CERTIFICATE----- / -----BEGIN) before submission.

System Settings tab

Requires global admin for the SSO section; log retention and API products also act on a specific environment.

Log Retention Policies — set access-log, audit-log, and observation-data retention (in days, 1–3650) per environment. Governs automatic cleanup.
SSO Admin Authentication — register an OpenID Connect identity provider for the console: provider key, display name, issuer URL, client ID/secret, and whether to auto-provision admin users on first SSO login. Once configured, the provider key is what you enter into the config bar’s Sign in with SSO field.
API Products & Plans — define a marketed bundle of APIs (an API Product, with name/slug/description/visibility) that developers can subscribe to in the portal; each product then gets one or more Plans with per-minute/day/month rate limits.

AI Recommendations tab

Shows AI-generated policy recommendations (rate limits, CORS, security, performance) derived from analyzing traffic patterns for an environment. Recommendations can be dismissed individually.