AI Gateway management API reference

The AI Gateway management API exposes caller identity and gateway-wide model and MCP server catalogs. It reads the owning AIGateway resource through the Kubernetes API. See Configure the AI Gateway for deployment and AI Gateway for configuration guides.

Base URL

The operator creates this Service in the AIGateway resource's namespace when spec.auth.virtualAPIKeys.enabled is true. <AIGATEWAY_NAME> is the resource's metadata.name. The management API uses HTTP port 8080; the gateway's model inference endpoint serves model requests separately. To expose the management API externally, route to this Service and use that route's HTTPS base URL.

With the default Service name and port, the in-cluster base URL is:

http://<AIGATEWAY_NAME>-api-key-service.<NAMESPACE>.svc:8080

Check that the Service exists and confirm its ports:

kubectl get svc -n <NAMESPACE>

For a local connection, forward the Service's HTTP port:

kubectl port-forward -n <NAMESPACE> svc/<SERVICE_NAME> 8080:8080

Replace <SERVICE_NAME> with the installed Service name. Keep the command running in a separate terminal. Your local base URL is http://localhost:8080. Append each endpoint path to the base URL once; for example, http://localhost:8080/v1/me. API authentication still applies when using a port-forward.

For external access, ask your platform administrator for this API's HTTPS base URL. To publish it, configure your ingress or gateway controller to route to <AIGATEWAY_NAME>-api-key-service on port 8080 in the Service's namespace, using the installed name and port if overridden.

The request examples below use http://localhost:8080, which matches the port-forward above. For calls from inside the cluster or through an external endpoint, replace that address with your deployment's base URL.

Endpoints

• Scope
• Authentication and authorization
• Catalog
  • getList all MCP servers visible to the gateway.
  • getList the models the calling user may use.
  • getReturn the owning gateway's identity.
• Introspection
  • getReturn the caller's identity and resolved management roles.

API docs by Redocly

Stacklok LLM Gateway Management API (0.1.0)

Download OpenAPI specification:Download

URL: https://github.com/stacklok/stacklok-llm-gateway License: Apache-2.0

Gateway-scoped HTTP API backing caller introspection and model/MCP catalogs. Endpoints read the owning AIGateway and, for /v1/me, the authenticated caller's identity directly from the apiserver. No parallel store.

Scope

Each API server instance is bound to exactly one Kubernetes namespace (configured via operator flag) and the AIGateway it serves lives in that namespace. The namespace is therefore not in the URL path; multi-namespace deployments run multiple API instances.

Authentication and authorization

All requests require a bearer JWT validated against the OIDC provider configured on the target AIGateway (spec.auth.oidc). /v1/me also returns roles resolved from AIGateway.spec.auth.authz.roles.

Catalog

List all MCP servers visible to the gateway.

Forward-compatible; always returns an empty items array in Phase 8. Enforcement lands in a later phase.

Authorizations:

BearerAuth

header Parameters

X-Request-Id

string Correlation ID; echoed on responses and included in audit records.

Responses

http://localhost:8080/v1/mcp-servers

Response samples

• 200
• 401
• 429
• 503

Content type

application/json

{

• "items": [

  • {

    • "description": "string",
    • "name": "string",
    • "ready": true

    }

  ]

}

List the models the calling user may use.

Derived from the owning AIGateway's spec.routes[].match.model, then filtered to the caller's effective model access as the Directory decides it — so this surface and the data-plane GET /v1/models intercept always agree about what the caller may call. Deduplicated and sorted by model id, OpenAI-shaped (object:"list", data[]) to match that intercept.

?scope=all returns the complete configured catalog instead, unfiltered, for an Admin authoring a Model Set — who must be able to grant models their own access does not include. It requires the deployment's admin role.

Authorizations:

BearerAuth

query Parameters

scope

string Value: "all" Set to all for the complete configured catalog, unfiltered. Requires the admin role.

header Parameters

X-Request-Id

string Correlation ID; echoed on responses and included in audit records.

Responses

http://localhost:8080/v1/models

Response samples

• 200
• 400
• 401
• 403
• 404
• 429
• 503

Content type

application/json

{

• "data": [

  • {

    • "context_window": 200000,
    • "created": 1690000000,
    • "display_name": "string",
    • "id": "openai/gpt-4o-mini",
    • "object": "model",
    • "owned_by": "openai"

    }

  ],
• "object": "list"

}

Return the owning gateway's identity.

Returns the AIGateway name and namespace this api-key-service serves. Sourced from the operator-injected GATEWAY_NAME / GATEWAY_NAMESPACE — authoritative and unambiguous.

Authorizations:

BearerAuth

header Parameters

X-Request-Id

string Correlation ID; echoed on responses and included in audit records.

Responses

http://localhost:8080/v1/info

Response samples

• 200
• 401

Content type

application/json

{

• "name": "prod-gateway",
• "namespace": "llm-gateway"

}

Introspection

Return the caller's identity and resolved management roles.

Returns subject, groups, and resolved management roles.

Authorizations:

BearerAuth

header Parameters

X-Request-Id

string Correlation ID; echoed on responses and included in audit records.

Responses

http://localhost:8080/v1/me

Response samples

• 200
• 401

Content type

application/json

{

• "email": "admin@example.com",
• "groups": [

  • "string"

  ],
• "roles": [

  • "string"

  ],
• "subject": "github|42"

}