Custom SSL certificate for ActiveGate

• 6-min read
• Updated on Feb 24, 2026

Connection to ActiveGate, from OneAgents or REST API, takes place over an encrypted HTTPS channel. ActiveGate presents a self-signed authentication certificate to all connecting clients. While OneAgent instances may ignore the validity of ActiveGate certificates (depending on configuration), connections from browser clients (such as the RUM JavaScript) do verify that the hostname listed in the certificate is correct, before they send data.

ActiveGate can serve a custom certificate instead of the default one.

Configure a custom SSL certificate

agctl ssl-certificate set --certificate=/path/to/cert.crt --key=/path/to/key.pem

agctl ssl-certificate set --certificate=/path/to/cert.crt --key=/path/to/key.pem --pem-password=secret --password=changeit --alias=mycert

Managing certificates via REST API

The certificates can be managed remotely via REST API. Prepare a PKCS#12 certificate file and you can upload it to ActiveGate using REST.

Upload and activate certificate

The following REST point uploads and activates the selected certificate file. The password for the file must be the same as the password for the keys contained in the file, and they must be provided in an X-Password custom HTTP header.

curl https://{address of ActiveGate}:{port}/e/{environment ID}/api/v1/certificate/{certificate file name} -H"Authorization: Api-Token {token}" -H"X-Password: {password}" -H"Content-Type: application/octet-stream" -T {path to certificate file}

For example:

curl https://myActiveGate:9999/e/myEnvironmentId/api/v1/certificate/cert.p12 \
  -H "Authorization: Api-Token 123abc" \
  -H "X-Password: myPassword" \
  -H "Content-Type: application/octet-stream" \
  -T cert.p12

If the API call is successful, the HTTP response will be 200 with JSON-formatted description of the content of the activated certificate file.

If the API call fails, the HTTP response will be a 4xx or 5xx error code, with a plain text message.

Replace active certificate

You can't replace an active certificate using this endpoint. The operation will return HTTP 403 Forbidden. To replace an active certificate, upload a new certificate under a different name, then delete the old certificate.

Delete certificate

Deletes the selected certificate on ActiveGate.

curl -XDELETE https://myActiveGate:9999/e/myEnvironmentId/api/v1/certificate/cert.p12 -H"Authorization: Api-Token 123abc"

If the certificate is deleted successfully, the API call will respond with HTTP 200 code with no content.

If the file with the specified name does not exist, the API call will respond with HTTP 404 Not found code.

If the certificate file is currently in use, the API call will respond with HTTP 403 Forbidden code.

Activate certificate

Activates an existing previously-uploaded certificate file using the specified password.

curl -XPOST https://myActiveGate:9999/e/myEnvironmentId/api/v1/certificate/cert.p12/activate -H"Authorization: Api-Token 123abc" -d"{\"password\":\"pass\"}"

curl -XPOST https://myActiveGate:9999/e/myEnvironmentId/api/v1/certificate/cert.p12/activate -H"Authorization: Api-Token 123abc" -H"X-Password: pass"

If the certificate is successfully activated, the API call will respond with HTTP 200 code, with JSON-formatted description of the content of the activated certificate file.

If the requested certificate file does not exist on the ActiveGate, the API call will respond with HTTP 404 code.

If the provided password does not match, the API call responds with HTTP 400 code.

List all certificates

Returns a JSON-formatted list of all uploaded files.

curl https://myActiveGate:9999/e/myEnvironmentId/api/v1/certificate/list -H"Authorization: Api-Token 123abc"

If the active keystore is on the list, its entry will contain additional details.

Example response:

[
   {
      "name":"cert_demo.p12"

},
   {      "name":"cert.p12",
      "desc":[         {
            "alias":"local",
            "description":"Subject:CN=myActiveGate;Valid from:Fri Feb 15 13:16:58 CET 2019;Valid to:Sat Feb 15 13:16:58 CET 2020;Serial number:71d275dd3983c3cb9382437275dd3983c3cb93dbca"

},
         {
            "alias":"dynatrace",
            "description":"Subject:CN=*.clients.dynatrace.org;Valid from:Thu Feb 21 10:06:03 CET 2019;Valid to:Fri Feb 21 10:06:03 CET 2020;Serial number:6dc7008ab269ecebeed03652ce08ab269ecebeeeb33"

}

]

},
   {
      "name":"cert_key_1.p12"

}
]

Note that the default self-signed certificate is not included in the list.

Describe certificate

This API call returns a JSON-formatted description of the selected file.

curl https://myActiveGate:9999/e/myEnvironmentId/api/v1/certificate/cert.p12/list -H"Authorization: Api-Token 123abc" -H"X-Password: pass"

curl -XPOST https://myActiveGate:9999/e/myEnvironmentId/api/v1/certificate/cert.p12/list -H"Authorization: Api-Token 123abc" -H"X-Password: pass"

curl -XPOST https://myActiveGate:9999/e/myEnvironmentId/api/v1/certificate/cert.p12/list -H"Authorization: Api-Token 123abc" -d"{\"password\":\"pass\"}"

If the requested certificate file does not exist on the ActiveGate, the API call will respond with HTTP 404 code.

If the password doesn't match, the API call responds with HTTP 400 code.

Example response:

{   "name":"cert.p12",
   "desc":[      {
         "alias":"local",
         "description":"Subject:CN=myActiveGate;Valid from:Fri Feb 15 13:16:58 CET 2019;Valid to:Sat Feb 15 13:16:58 CET 2020;Serial number:7137275dd398c4182437275dd3983c3cb93dbca"

},
      {
         "alias":"dynatrace",
         "description":"Subject:CN=*.clients.dynatrace.org;Valid from:Thu Feb 21 10:06:03 CET 2019;Valid to:Fri Feb 21 10:06:03 CET 2020;Serial number:6d2ce08ab269ecebeee7f1bd03652ce08ab269ecebeeeb33"

}

]
}

Create a certificate file for testing

To create a self-signed PKCS#12 certificate file for testing

Known limitations and support for multiple certificates