Management API Access

1. Overview

The admin-service exposes Spring Boot Actuator management endpoints at the /management base path. These endpoints provide runtime inspection and control capabilities including log level management, health checks, metrics, and cache operations.

2. Authentication

Management endpoints are secured with ROLE_ADMIN. There are two ways to authenticate:

2.1. API Key Authentication

For automated or service-to-service access, use an API key with ADMIN permission via the X-API-KEY header:

curl -H "X-API-KEY: <api-key-uuid>" https://<host>/management/<endpoint>

The API key must:

  • Be marked as active in the api_key table

  • Have an api_key_permission record with role = 'ADMIN'

2.2. JWT Authentication

Users authenticated via the standard JWT flow with ROLE_ADMIN can also access management endpoints through the admin UI or direct API calls with a Bearer token.

3. Public Endpoints

These endpoints are accessible without authentication:

Endpoint Method Description

/management/health

GET

Application health status

/management/health/liveness

GET

Kubernetes liveness probe

/management/health/readiness

GET

Kubernetes readiness probe

/management/info

GET

Build and git information

/management/prometheus

GET

Prometheus metrics (for scraping)

4. Protected Endpoints

These endpoints require ROLE_ADMIN authentication.

4.1. Log Level Management

Inspect and change logger levels at runtime without restarting the application.

# View all loggers and their levels
curl -H "X-API-KEY: <key>" https://<host>/management/loggers

# View a specific logger
curl -H "X-API-KEY: <key>" https://<host>/management/loggers/za.co.idealogic

# Change log level
curl -X POST -H "X-API-KEY: <key>" -H "Content-Type: application/json" \
  -d '{"configuredLevel": "DEBUG"}' \
  https://<host>/management/loggers/za.co.idealogic.event.admin.security

Common log levels: TRACE, DEBUG, INFO, WARN, ERROR, OFF

Log level changes take effect immediately and persist until the next restart. They are not persisted across restarts.

4.2. Environment and Configuration

# View environment properties
curl -H "X-API-KEY: <key>" https://<host>/management/env

# View a specific property
curl -H "X-API-KEY: <key>" https://<host>/management/env/spring.datasource.url

# View loaded configuration properties
curl -H "X-API-KEY: <key>" https://<host>/management/configprops

4.3. Metrics

# List available metrics
curl -H "X-API-KEY: <key>" https://<host>/management/metrics

# View a specific metric
curl -H "X-API-KEY: <key>" https://<host>/management/metrics/jvm.memory.used
curl -H "X-API-KEY: <key>" https://<host>/management/metrics/http.server.requests

4.4. Cache Operations

See Cache Management for detailed cache inspection and eviction procedures.

5. Security Model

The security configuration for management endpoints is defined in SecurityConfiguration.java:

  • /management/health/**, /management/info, /management/prometheus → public access

  • /management/** → requires ROLE_ADMIN authority

The ApiKeyFilter runs before the standard Bearer token filter. When an API key with ADMIN permission is provided, the request is authenticated with ROLE_API_KEY and ROLE_ADMIN authorities, granting access to all management endpoints.