Try it free

EdgeConnect reference

  • Latest Dynatrace
  • Reference
  • 14-min read
  • Published Oct 01, 2026

This page includes reference details for working with EdgeConnect. It covers the user permissions required to manage configurations, the edgeConnect.yaml configuration fields and their environment variables, secrets for authenticating outgoing requests, TLS certificate troubleshooting, and the system requirements and limits that apply to each EdgeConnect container.

User permissions

By default, platform users have only read-only access to EdgeConnect configurations through the app-engine:edge-connects:read permission, bound to the Standard and Pro default policies.

To manage EdgeConnect configurations, you need to belong to a group with the required IAM permissions. The Admin default policy already contains the necessary scopes, so an admin user can fully manage EdgeConnect configurations by default.

To create your own admin policy, include the following permissions:

Read EdgeConnect configurations

ALLOW app-engine:edge-connects:read;

Create a new EdgeConnect configuration

ALLOW app-engine:edge-connects:write, oauth2:clients:manage WHERE oauth2:scopes = "app-engine:edge-connects:connect";

You need OAuth client management permission to create the OAuth client for a new EdgeConnect.

Update an EdgeConnect configuration

ALLOW app-engine:edge-connects:write;

Rotate the OAuth client secret of an EdgeConnect

ALLOW oauth2:clients:manage where oauth2:scopes="app-engine:edge-connects:connect";

Delete an EdgeConnect

ALLOW app-engine:edge-connects:delete, oauth2:clients:manage WHERE oauth2:scopes = "app-engine:edge-connects:connect";

You need OAuth client management permission to delete the OAuth client for an EdgeConnect.

To adjust the policies and group memberships of users:

  1. Go to Account Management > Identity & access management.
  2. Select People, Groups, or Policies.

For more information, see Manage IAM policies.

EdgeConnect configuration file

The following table lists the configuration fields and the names of the corresponding environment variables. Some environment variable names use both single (_) and double underscore symbols (__).

When you run EdgeConnect in Kubernetes with Dynatrace Operator, you configure these settings through the EdgeConnect custom resource instead. For details, see EdgeConnect Operator parameters.

FieldEnvironment variableDescription

name

EDGE_CONNECT_NAME

The technical identifier of the EdgeConnect. This needs to match the name you specified when you created the configuration.

api_endpoint_host

EDGE_CONNECT_API_ENDPOINT_HOST

Your environment base URL.

oauth.endpoint

EDGE_CONNECT_OAUTH__ENDPOINT

The token endpoint URL of Dynatrace SSO.

oauth.client_id

EDGE_CONNECT_OAUTH__CLIENT_ID

The ID of the OAuth client created with the EdgeConnect configuration.

oauth.client_secret

EDGE_CONNECT_OAUTH__CLIENT_SECRET

The secret of the OAuth client created with the EdgeConnect configuration. To rotate it, call Rotate an EdgeConnect OAuth client secret—the response returns the new secret—then set this value in the edgeConnect.yaml file of every instance of the configuration and restart the containers.

oauth.resource

EDGE_CONNECT_OAUTH__RESOURCE

The URN identifying your tenant.

restrict_hosts_to Optional

EDGE_CONNECT_RESTRICT_HOSTS_TO

Restricts outgoing HTTP requests to the specified hosts.

The field supports wildcards (for example, *.myapp.org matches staging.myapp.org and prod.myapp.org). Use a YAML list or separate entries with commas. For behavior details, see Host restrictions.

certificate_paths Optional

EDGE_CONNECT_CERTIFICATE_PATHS

Paths to the TLS certificates EdgeConnect uses to verify hosts over HTTPS and secure WebSockets.

Mount the certificate files at these paths inside the container. Supported formats: PEM (.pem, .crt, .cer) and DER (.der). For more information, see the TLS certificate instructions.

proxy.server Optional

EDGE_CONNECT_PROXY__SERVER

Server address (hostname or IP address) of the proxy.

proxy.port Optional

EDGE_CONNECT_PROXY__PORT

Port of the proxy.

proxy.exceptions Optional

EDGE_CONNECT_PROXY__EXCEPTIONS

A list of hosts that EdgeConnect should not reach through the configured proxy.

You can use a wildcard to replace the first parts of a host domain. Use a YAML list or separate multiple entries with commas. For example, *.myapp.org matches staging.myapp.org and prod.myapp.org.

proxy.auth.user Optional

EDGE_CONNECT_PROXY__AUTH__USER

Username for authentication with the proxy, using the Basic HTTP authentication scheme.

proxy.auth.password Optional

EDGE_CONNECT_PROXY__AUTH__PASSWORD

Password for authentication with the proxy, using the Basic HTTP authentication scheme.

secrets Optional

N/A

An optional list of secrets. See Secrets for the fields of each list item.

Host restrictions

When you set restrict_hosts_to:

  • EdgeConnect rejects all other requests, including requests to hosts that don't match the configured host patterns specified in host pattern mapping.
  • This restriction is additional. You still need to configure a host pattern mapping to allow EdgeConnect to connect to your internal resources.

Secrets

When apps and workflows send requests to services outside the Dynatrace platform, they often need secrets to authenticate (for example, API tokens or secrets within webhook URLs). To avoid accidental exposure, don't store plain-text secret values in your apps or workflows.

Use placeholder tokens in request headers, query parameters, and bodies. At runtime, EdgeConnect securely replaces them with the secret values defined in your edgeConnect.yaml file.

EdgeConnect can read secrets from two sources: environment variables, or files mounted into the EdgeConnect container. For the configuration steps, see Inject secrets into requests.

FieldEnvironment variableDescription

name

N/A

A human-readable name that identifies your secret. EdgeConnect uses this name for logging.

token

N/A

A placeholder for a secret that you can include in your requests.

EdgeConnect replaces occurrences of the token in query parameters, headers, and bodies with the secret's value. For the token format and how to generate one, see Token format.

from_env Optional

N/A

The environment variable that holds the secret value. Configure exactly one of from_env or from_file.

from_file Optional

N/A

The file that contains the secret value. Configure one of from_env or from_file.

restrict_hosts_to

N/A

The list of hosts that can receive this secret. When a request targets one of these hosts, EdgeConnect scans query parameters, headers, and request bodies for the configured token and replaces it with the secret value.

To prevent accidental secret exposure, EdgeConnect rejects requests containing the token when they target hosts outside restrict_hosts_to.

Token format

Secret tokens use the format dt0e01.<token_name>.<token_secret>, where:

  • <token_name>: 15-character base-32 string.
  • <token_secret>: 40-character base-32 string.

On Linux, you can generate a cryptographically secure token with the following command:

echo "dt0e01.`openssl rand -out /dev/stdout 15 \
| base32 \
| tr '[:lower:]' '[:upper:]'`.`\
openssl rand -out /dev/stdout 40 \
| base32 \
| tr '[:lower:]' '[:upper:]'`"

This command requires openssl on your system and the base32 utility. The base32 utility is part of GNU coreutils and is typically preinstalled on most Linux distributions.

TLS certificate troubleshooting

If EdgeConnect aborts an HTTPS connection due to a certificate verification failure, this can be caused by incomplete configuration or invalid SSL certificates.

The following table lists common HTTPS connection errors that might appear in the EdgeConnect logs.

Error messageExplanationSuggested action

"self-signed certificate"

"self-signed certificate in certificate chain"

"unable to get issuer certificate"

"unable to get local issuer certificate"

These errors indicate that EdgeConnect can't verify the CA certificates that sign the target host's certificate.

List all certificates that directly or indirectly sign the target server's certificate in the certificate_paths configuration field.

"hostname mismatch"

This error occurs when a server presents a certificate that doesn't match the hostname EdgeConnect is trying to reach. For example, something might intercept the TLS connection within your network or redirect it to a different host.

Make sure EdgeConnect's network traffic isn't subject to unintended interception or redirection.

"certificate has expired"

This error indicates that the certificate of the target host, or one of the CA certificates used to sign it, has expired.

Make sure all certificates in the certificate chain are still valid, and renew any expired ones.

System requirements

For a typical EdgeConnect deployment, we recommend 1 GB of memory and 1 CPU. Memory requirements might vary based on the payload size of the requests EdgeConnect handles.

EdgeConnect requires the following outbound network connectivity:

  • HTTPS (443) to https://sso.dynatrace.com/sso/oauth2/token
  • HTTPS (443) and WebSocket Secure (WSS/443) to https://<your environment ID>.apps.dynatrace.com, and to any target system EdgeConnect requests need to reach.

Limits

The following limits apply to EdgeConnect requests and responses to ensure EdgeConnect performs well:

LimitDescription

Request timeout

Every request that runs over EdgeConnect has a 120-second timeout, which matches the maximum execution time of functions. If a function times out, EdgeConnect automatically cancels all its outgoing requests.

Payload size limit

The body of a request or response run over EdgeConnect can't exceed 6 MB. Requests that exceed this limit fail with HTTP error code 400.

Concurrent requests limit

A single EdgeConnect container can process up to 20 concurrent requests. Additional requests are likely to hit the request timeout. To work around this limit, deploy more EdgeConnect containers.

Related topics

  • EdgeConnect concepts
  • Get started with EdgeConnect
Related tags
Infrastructure Observability