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 # mandatory
    secrets: # optional
      url-base-path: <secrets-base-path> # optional
    metrics: # optional
      prometheus: # optional
        url-base-path: <prometheus-base-path> # optional
        labels: # optional
          <label-name-1>: <label-value-1>
          <label-name-2>: <label-value-2>
          <label-name-3>: <label-value-3>

• 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. Set url-base-path to customize baes URL 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 # mandatory
    tls: # mandatory
      cert-file : <path-to-cert-file> # mandatory
      key-file : <path-to-key-file> # mandatory
      ca-file : <path-to-ca-file> # optional - needed for mutual tls only
    secrets: # optional
      url-base-path: <secrets-base-path> # optional
    metrics: # optional
        prometheus: # optional
          url-base-path: <prometheus-base-path> # optional
          labels: # optional
            <label-name-1>: <label-value-1>
            <label-name-2>: <label-value-2>
            <label-name-3>: <label-value-3>

• 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. Optional Labels can be configured.

Fetch secrets with HTTP/HTTPS endpoint (optional)

• Use HTTP/HTTPS endpoints exclusively for Prometheus; you can also disable secret fetching.
• By default, configuring an HTTP/HTTPS endpoint enables Prometheus scraping via the default path.

service:
 http:
   endpoint: 0.0.0.0:8443

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

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

• Get secret: GET /manage/rest/v1/secrets/RESOURCE_NAME/SECRET_KEY

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

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}
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