> For the complete documentation index, see [llms.txt](https://docs.kangal.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kangal.dev/admin-api/api-reference.md). # Admin API overview Kangal's Admin API manages tenants, gateways, routing resources, policies, configuration bundles, observability, SLOs, and administrative credentials. This page documents conventions shared by the implemented routes; use the generated OpenAPI schema for complete endpoint-specific request and response models. ## Base URL and versioning The current API version is `v1`: ```bash export KANGAL_URL='https://kangal.example.com' curl -fsS "$KANGAL_URL/api/versions" | jq curl -fsS "$KANGAL_URL/openapi.json" -o kangal-openapi.json ``` The application registers both `/admin/...` and `/api/v1/admin/...`. New clients should use `/api/v1/admin/...` so a later version can be adopted explicitly. Interactive FastAPI documentation is normally available at `/docs`; deployments may restrict it at the ingress. The OpenAPI document remains the authoritative inventory for endpoint-specific fields and status codes. ## Authentication Send a bearer token on every Admin API request: ```bash export KANGAL_TOKEN='kangaladm_...' curl -fsS \ -H "Authorization: Bearer $KANGAL_TOKEN" \ "$KANGAL_URL/api/v1/admin/gateways?tenant_id=tenant-acme" | jq ``` Admin API tokens are created by `POST /api/v1/admin/api-tokens`, start with `kangaladm_`, and are returned in plaintext only at creation. User access and refresh tokens come from `POST /auth/login`. See [Authentication, pagination, and errors](/admin-api/auth-pagination-errors.md) for role, scope, and tenant behavior. ## Endpoint families | Family | Example paths | Notes | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | Gateways |

/api/v1/admin/gateways
/api/v1/admin/gateways/{gateway\_id}/overview
/api/v1/admin/gateways/{gateway\_id}/traffic/recent

| Tenant gateway management and operational overview. | | Services and routes |

/api/v1/admin/gateways/{gateway\_id}/services
/api/v1/admin/gateways/{gateway\_id}/routes

| Gateway routing resources. | | Upstreams and targets |

/api/v1/admin/gateways/{gateway\_id}/upstreams
/api/v1/admin/gateways/{gateway\_id}/targets
/api/v1/admin/gateways/{gateway\_id}/targets/upstream/{upstream\_id}

| Backend pools and target instances. | | Certificates and SNI |

/api/v1/admin/gateways/{gateway\_id}/certificates
/api/v1/admin/gateways/{gateway\_id}/ca-certificates
/api/v1/admin/gateways/{gateway\_id}/snis

| TLS material and hostname mapping under a gateway. | | Consumers and credentials |

/api/v1/admin/consumers
/api/v1/admin/consumer-credentials
/api/v1/admin/consumer-groups

| Client identity and policy grouping. | | Admin API tokens | `/api/v1/admin/api-tokens` | Machine credential lifecycle. | | Configuration |

/api/v1/admin/config/export
/api/v1/admin/config/validate
/api/v1/admin/config/diff
/api/v1/admin/config/import
/api/v1/admin/config/sync
/api/v1/admin/config/snapshots
/api/v1/admin/config/snapshots/{snapshot\_id}/rollback

| Declarative configuration and recovery. | | Observability |

/api/v1/admin/observability/summary
/api/v1/admin/observability/requests
/api/v1/admin/observability/requests/{request\_id}
/api/v1/admin/observability/live
/api/v1/admin/observability/anomalies
/api/v1/admin/observability/retention

| Correlated request metadata. | | SLOs |

/api/v1/admin/slos
/api/v1/admin/slos/evaluate
/api/v1/admin/slos/{slo\_id}/evaluate
/api/v1/admin/slos/{slo\_id}/acknowledge
/api/v1/admin/slos/{slo\_id}/timeline

| Objective definitions, evaluated state, and alert timeline. | | Audits | `/api/v1/admin/audits/` | Immutable administrative change records; requires a user access JWT. | The table is an orientation aid, not a replacement for OpenAPI. Some resource families use nested or gateway-scoped identifiers that are visible in their generated path definitions. ## Request conventions JSON is the default request and response format: ```bash curl -fsS -X POST \ -H "Authorization: Bearer $KANGAL_TOKEN" \ -H 'Content-Type: application/json' \ "$KANGAL_URL/api/v1/admin/gateways/gw-production/services" \ -d '{ "tenant_id": "tenant-acme", "name": "orders", "url": "https://orders.internal" }' | jq ``` Configuration endpoints also accept YAML with `Content-Type: application/yaml` or `?format=yaml`; use `Accept: application/yaml` for YAML export. Resource creation commonly returns `201 Created`, reads and updates return `200 OK`, and successful deletes may return `204 No Content`. Do not run `jq` against an empty 204 body. ```bash status=$(curl -sS -o /tmp/kangal-response.json -w '%{http_code}' \ -X DELETE \ -H "Authorization: Bearer $KANGAL_TOKEN" \ "$KANGAL_URL/api/v1/admin/gateways/gw-production/services/SERVICE_ID") printf 'HTTP %s\n' "$status" test -s /tmp/kangal-response.json && jq . /tmp/kangal-response.json ``` ## Request correlation Send a stable `X-Request-ID` from an automation job or support case. Kangal returns the selected identifier as `X-Request-ID` and uses it in request context where the route supports correlation. ```bash curl -i \ -H "Authorization: Bearer $KANGAL_TOKEN" \ -H 'X-Request-ID: change-1842-export' \ "$KANGAL_URL/api/v1/admin/config/export?tenant_id=tenant-acme" ``` Avoid embedding credentials or personal data in request IDs because they can appear in logs and audit context. ## Tenant selection Tenant-aware endpoints commonly accept `tenant_id` in the query or request body. Behavior varies by route family: * Observability and SLO routes resolve the caller's tenant and reject regular-admin cross-tenant requests. * Audit queries from regular admins are forced to their own tenant; super admins can query globally or filter. * Configuration endpoints use explicit tenant values, and sync rejects query/body mismatch. Use tenant-scoped credentials and ensure both values match the intended tenant. * A super admin without an assigned tenant must pass an explicit tenant on tenant-scoped observability/SLO operations. Never infer a tenant from a resource name. Use stable IDs and validate the active context before a write. ## Discover an endpoint schema List versioned Admin API operations: ```bash jq -r ' .paths | to_entries[] | select(.key | startswith("/api/v1/admin/")) | .key as $path | .value | to_entries[] | "\(.key | ascii_upcase) \($path)" ' kangal-openapi.json | sort ``` Inspect one operation and its request body: ```bash jq '.paths["/api/v1/admin/config/sync"].post' kangal-openapi.json ``` OpenAPI references schemas under `.components.schemas`. Resolve the `$ref` named by the operation instead of guessing field names from another route family. ## Safe automation ```bash set -euo pipefail request_id="deploy-${CI_PIPELINE_ID:-manual}-$(date +%s)" response=$(mktemp) headers=$(mktemp) code=$(curl -sS \ --connect-timeout 5 \ --max-time 30 \ --retry 2 \ --retry-connrefused \ -D "$headers" \ -o "$response" \ -w '%{http_code}' \ -H "Authorization: Bearer $KANGAL_TOKEN" \ -H "X-Request-ID: $request_id" \ "$KANGAL_URL/api/v1/admin/gateways?tenant_id=$TENANT_ID") if (( code < 200 || code >= 300 )); then printf 'Kangal request failed: HTTP %s, request_id=%s\n' "$code" "$request_id" >&2 jq . "$response" 2>/dev/null || cat "$response" >&2 exit 1 fi jq . "$response" ``` Retry reads and connection establishment conservatively. Do not automatically retry a timed-out write unless the operation is known to be idempotent or live state has been checked; configuration imports can be partially applied. ## Health and metrics ```bash curl -fsS "$KANGAL_URL/health" | jq curl -fsS "$KANGAL_URL/ready" | jq curl -fsS "$KANGAL_URL/metrics" | head ``` `/metrics` has no application bearer-token dependency and should be protected by network policy. Health endpoints prove process/readiness state, not that an individual tenant configuration is correct; follow writes with resource reads and route smoke tests. ## Compatibility guidance * Pin integrations to `/api/v1` and regenerate clients from the deployed OpenAPI document. * Tolerate additive response fields. * Treat enum and validation failures as contract feedback, not values to silently coerce. * Read pagination headers where documented and preserve `X-Request-ID` in logs. * Use `kangalctl` for repository-supported operator workflows instead of maintaining ad hoc wrappers for common CRUD and config operations. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.kangal.dev/admin-api/api-reference.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.