--- title: "Configure HTTP and HTTPS" description: "Configure HTTP/HTTPS listeners in Aerospike Secret Agent for RESTful secret retrieval and Prometheus metrics." --- # Configure HTTP and HTTPS > For the complete documentation index see: [llms.txt](https://aerospike.com/docs/llms.txt) > > All documentation pages available in markdown. 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: ```yaml service: http: endpoint: 0.0.0.0:8080 # mandatory secrets: # optional url-base-path: # optional metrics: # optional prometheus: # optional url-base-path: # optional labels: # optional : : : ``` - **`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](#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: ```yaml service: https: endpoint: 0.0.0.0:8443 # mandatory tls: # mandatory cert-file : # mandatory key-file : # mandatory ca-file : # optional - needed for mutual tls only secrets: # optional url-base-path: # optional metrics: # optional prometheus: # optional url-base-path: # optional labels: # optional : : : ``` - **`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. ```yaml 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](https://aerospike.com/docs/database/tools/secret-agent/template)). ## Request and response **Success (200)** `Content-Type: application/json` ```json { "secretValue": "" } ``` **Error (404 or 500)** `Content-Type: application/json` ```json { "error": "" } ``` ## Examples ### Fetch secret over HTTP Terminal window ```bash curl -s http://localhost:8080/manage/rest/v1/secrets/MyResource/MyKey ``` Example response: ```json {"secretValue":"my-secret-value"} ``` ### Fetch secret over HTTPS Without server certificate verification (for example, dev or self-signed): Terminal window ```bash curl -sk https://localhost:8443/manage/rest/v1/secrets/MyResource/MyKey ``` With CA certificate (verify server): Terminal window ```bash curl --cacert /path/to/ca.pem https://localhost:8443/manage/rest/v1/secrets/MyResource/MyKey ``` With client certificate (mTLS): Terminal window ```bash 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: ```yaml 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: Terminal window ```bash curl --cacert /path/to/ca.pem https://localhost:8443/myapp/secrets/v1/secrets/MyResource/MyKey ```