Configure HTTP and HTTPS

Use an HTTP or HTTPS listener when clients, such as orchestrators, sidecars, scripts, or other services, need to fetch secrets using standard HTTP semantics.

Note

HTTP and HTTPS listeners are available in Secret Agent 1.3.0 and later.

HTTP (plaintext)

HTTP is unencrypted. Use HTTP only for local or trusted networks.

To configure an HTTP listener, add an http section to the service context in your Secret Agent configuration file:

service:
  http:
    endpoint: 0.0.0.0:8080
    secrets: {}                    # optional; enables REST secrets API with defaults
    metrics:                       # optional; enables Prometheus metrics
      prometheus: {}

• endpoint (required): Listen address and port (for example, 0.0.0.0:8080).
• secrets (optional): Enables the REST secrets API. Use {} for default base path /manage/rest. To use a custom path, set url-base-path (see URL base path validation).
• metrics (optional): Enables Prometheus metrics over HTTP. Use prometheus: {} for default base path, or set url-base-path and optional labels.

HTTPS with TLS

In production environments, we recommend using HTTPS so that secrets and metrics are not sent in the clear.

To configure an HTTPS listener, add an https section with TLS configuration to the service context in your Secret Agent configuration file:

service:
  https:
    endpoint: 0.0.0.0:8443
    tls:
      cert-file: /path/to/cert.pem
      key-file:  /path/to/key.pem
      ca-file:   /path/to/ca.pem   # optional; for mutual TLS
    secrets: {}
    metrics:
      prometheus: {}

• endpoint (required): Listen address and port (for example, 0.0.0.0:8443).
• tls (required for HTTPS): Server certificate and private key; ca-file is optional and used for client certificate verification (mTLS).
• secrets and metrics: Base paths default to /manage/rest unless you set url-base-path.

URL base path validation

The following options accept an optional url-base-path that prefixes the secrets API and Prometheus endpoints:

• service.http.secrets.url-base-path
• service.http.metrics.prometheus.url-base-path
• service.https.secrets.url-base-path
• service.https.metrics.prometheus.url-base-path

Default when omitted: /manage/rest.

Validation rules (invalid values cause startup failure):

• Length ≥ 2
• Must start with /
• Must not end with /

Invalid examples: manage/rest (no leading /), /manage/rest/ (trailing /).

REST endpoints

Method	Path	Description
GET	{secrets-url-base-path}/v1/secrets/{resource}/{secretkey}	Fetch secret value for the given resource and key
GET	{secrets-url-base-path}/v1/api-docs/	Swagger UI for API documentation

With default url-base-path /manage/rest:

• Get secret: GET /manage/rest/v1/secrets/RESOURCE_NAME/SECRET_KEY
• Swagger UI: GET /manage/rest/v1/api-docs/

Prometheus endpoints

Method	Path	Description
GET	{prometheus-url-base-path}/v1/prometheus	Custom Prometheus metrics
GET	{prometheus-url-base-path}/v1/prometheus_go	Go runtime Prometheus metrics

With default base path /manage/rest, the full URLs are /manage/rest/v1/prometheus and /manage/rest/v1/prometheus_go. You can set a different base path for Prometheus than for secrets (see Configuration template).

Request and response

Success (200)
Content-Type: application/json

{ "secretValue": "<secret-string>" }

Error (404 or 500)
Content-Type: application/json

{ "error": "<error-message>" }

Examples

Fetch secret over HTTP

curl -s http://localhost:8080/manage/rest/v1/secrets/MyResource/MyKey

Example response:

{"secretValue":"my-secret-value"}

Fetch secret over HTTPS

Without server certificate verification (for example, dev or self-signed):

curl -sk https://localhost:8443/manage/rest/v1/secrets/MyResource/MyKey

With CA certificate (verify server):

curl --cacert /path/to/ca.pem https://localhost:8443/manage/rest/v1/secrets/MyResource/MyKey

With client certificate (mTLS):

curl --cacert /path/to/ca.pem --cert /path/to/client.pem --key /path/to/client-key.pem https://localhost:8443/manage/rest/v1/secrets/MyResource/MyKey

Open API docs (Swagger)

• HTTP: http://localhost:8080/manage/rest/v1/api-docs/
• HTTPS: https://localhost:8443/manage/rest/v1/api-docs/

Open the URL in a browser to browse and try the REST secrets API.

Custom URL base paths

You can set different base paths for secrets and for Prometheus:

service:
  https:
    endpoint: 0.0.0.0:8443
    tls:
      cert-file: /path/to/cert.pem
      key-file:  /path/to/key.pem
    secrets:
      url-base-path: /myapp/secrets
    metrics:
      prometheus:
        url-base-path: /myapp/metrics

Resulting URLs:

Purpose	URL
Get secret	https://localhost:8443/myapp/secrets/v1/secrets/{resource}/{secretkey}
Swagger UI	https://localhost:8443/myapp/secrets/v1/api-docs/
Prometheus (custom)	https://localhost:8443/myapp/metrics/v1/prometheus
Prometheus (Go runtime)	https://localhost:8443/myapp/metrics/v1/prometheus_go

Example request with custom secrets path:

curl --cacert /path/to/ca.pem https://localhost:8443/myapp/secrets/v1/secrets/MyResource/MyKey

Trace logging for base URLs

At startup, Secret Agent logs the Prometheus and Secrets base URLs when the HTTP or HTTPS listener starts. To see these messages, set log.level to trace in your configuration:

log:
  level: trace

Restart Secret Agent and check the logs for lines such as:

• HTTP prometheus end point base URL is: /manage/rest
• HTTPS secret end point base URL is: /myapp/secrets

Troubleshooting

Symptom	Likely cause	Action
Startup fails: URL base path ”…” must start with ’/‘	Custom url-base-path has no leading /	Use a path that starts with / (for example, /manage/rest).
Startup fails: must not end with ’/‘	Trailing slash in url-base-path	Remove the trailing slash.
Request fails: no resource string specified	Client did not send resource (TCP/UDS) or path is missing resource (REST).	Always send the resource name. See Release notes for 1.3.0 single-resource behavior.
Request fails: resource not found in config: X	Resource name not in config or typo.	Check secret-manager.*.resources and use an exact key.
Need to confirm which paths are used	—	Set log.level: trace and check startup logs for Prometheus and Secrets base URLs.

Next steps

• Configuration template for all service.http and service.https options
• Metrics for Prometheus configuration and custom labels