> For the complete documentation index, see [llms.txt](https://docs.heisenware.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.heisenware.com/reference/functions/connectors/trusted-certificates.md).

# Trusted certificates

Trust the machines and servers on your own network once, for every connector.

When a connector opens a secure connection (`https://`, `mqtts://` and the like), the server shows a certificate: its ID card. Public web servers carry certificates every computer already trusts. A machine, a PLC or a server on your own network usually does not. It shows a certificate it made itself, or one your company made, and the connector refuses to connect:

```
GET https://192.168.1.10/api failed: self-signed certificate
```

The Trusted certificates functions (`TrustStore`) fix this once for the whole workspace. Every connector that opens a secure connection consults the same list: [HTTP / REST](https://docs.heisenware.com/reference/functions/connectors/http-rest.md), the [ctrlX Data Layer](https://docs.heisenware.com/reference/functions/connectors/ctrlx-data-layer.md), the [OPC UA client](https://docs.heisenware.com/reference/functions/connectors/opc-ua-client.md), [Hydra MIP](https://docs.heisenware.com/reference/functions/connectors/hydra-mip.md), the [MQTT client](https://docs.heisenware.com/reference/functions/connectors/mqtt-client.md), [Email](https://docs.heisenware.com/reference/functions/connectors/email.md), the [relational database](https://docs.heisenware.com/reference/functions/storage/relational-database.md) and the [timeseries database](https://docs.heisenware.com/reference/functions/storage/timeseries-database.md). No instance is needed, call the functions directly.

## Which function do I need?

| Situation                                                                             | Function                                 |
| ------------------------------------------------------------------------------------- | ---------------------------------------- |
| One device or server on my network refuses to connect.                                | `trustServer` with the server's address  |
| My IT gave me a company certificate (a "root CA" file) that vouches for many servers. | `addCertificateAuthority` with that file |
| I downloaded the server's certificate file from its web page.                         | `addServerCertificate` with that file    |
| What is trusted right now?                                                            | `list`                                   |
| Stop trusting something.                                                              | `remove`                                 |
| Look at a server's certificate before trusting it.                                    | `fetchServerCertificate`                 |

## Static functions

### `trustServer`

Looks at the certificate the server shows right now and stores it. From then on every connector accepts this server, also when the certificate is self-made, comes from an authority the workspace does not trust, or carries a different name than the address you use. Other servers of that authority stay untrusted.

Do this from a network you trust. Then compare the returned `fingerprint` with what the device shows in its own settings, so you know you trusted the right machine. When the server gets a new certificate later, call `trustServer` again: the stored one is replaced.

Databases (`postgres://`, `mysql://`, `mariadb://`) and mail servers (`smtp://`) start a connection unencrypted and switch on request. `trustServer` asks them the way their own clients do. A Microsoft SQL Server shows its certificate only inside its own protocol: add its certificate file with `addServerCertificate`.

{% hint style="info" %}
On a native agent, a server whose certificate an authority issued needs that authority instead (`addCertificateAuthority`). A self-made certificate works with `trustServer` everywhere.
{% endhint %}

#### Parameters

<table><thead><tr><th width="150">Input</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>url</code></td><td>The server's address, for example <code>https://192.168.1.10</code>, <code>192.168.1.10:8443</code>, <code>mqtts://broker.local</code>, <code>postgres://db.plant.local</code> or <code>smtp://mail.plant.local</code>. Without a port, the usual one of the kind of server: 8883 for <code>mqtts</code>, 465 for <code>smtps</code>, 587 for <code>smtp</code>, 5432 for <code>postgres</code>, 3306 for <code>mysql</code> and <code>mariadb</code>, 443 for any other.</td><td>string</td></tr><tr><td><code>name</code></td><td>A name for the stored certificate. Optional, the server's host name when omitted.</td><td>string</td></tr></tbody></table>

#### Example

```yaml
# url
https://192.168.1.10
```

#### Output

What is trusted now:

```yaml
name: 192.168.1.10
kind: server
subject: CN=ctrlx-core
issuer: CN=ctrlx-core
selfSigned: true
validFrom: '2026-01-01T00:00:00.000Z'
validTo: '2036-01-01T00:00:00.000Z'
fingerprint: 'AB:12:C3:...'
```

### `fetchServerCertificate`

Shows the certificate a server presents, without trusting it. Use it to check a device before `trustServer`, or to see why a connection fails.

#### Parameters

<table><thead><tr><th width="150">Input</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>url</code></td><td>The server's address, as for <code>trustServer</code>.</td><td>string</td></tr></tbody></table>

#### Output

The same fields as `trustServer` returns, plus `trusted` (whether the workspace accepts this server already) and `pem` (the certificate as text, should you want to keep it).

### `addServerCertificate`

Trusts one server by its certificate, when you have it as a file or as text, for example downloaded from the device's web page. Same effect as `trustServer`, without contacting the server.

#### Parameters

<table><thead><tr><th width="150">Input</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>certificate</code></td><td>The certificate as text (<code>-----BEGIN CERTIFICATE-----</code> ...) or the path to a certificate file (PEM or DER).</td><td>string</td></tr><tr><td><code>name</code></td><td>A name for the stored certificate. Optional, taken from the file name or the certificate itself when omitted.</td><td>string</td></tr></tbody></table>

#### Example

Upload the file with the [Files explorer](https://docs.heisenware.com/app-builder/app-builder/files.md), drag it to the parameter, and delete it from the uploads folder afterwards.

```yaml
# certificate
/shared/uploads/plc-gateway.pem
# name
plc-gateway
```

#### Output

What is trusted now, as for `trustServer`.

### `addCertificateAuthority`

Trusts every server whose certificate was issued by this authority. Use it when your IT hands you the company's certificate (a "root CA" or "issuing CA" file): one call, and all servers it vouches for are accepted. A file that holds several certificates is fine.

#### Parameters

<table><thead><tr><th width="150">Input</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>certificate</code></td><td>The authority's certificate as text or the path to its file (PEM or DER).</td><td>string</td></tr><tr><td><code>name</code></td><td>A name for the stored certificate. Optional, taken from the file name or the certificate itself when omitted.</td><td>string</td></tr></tbody></table>

#### Example

```yaml
# certificate
/shared/uploads/company-root-ca.pem
```

#### Output

What is trusted now, as for `trustServer`, with `kind: authority`.

### `list`

Lists everything the workspace trusts.

#### Output

One entry per stored certificate, with the fields `trustServer` returns. `kind` is `server` (one server) or `authority` (every server it vouches for). A file in the store that is not a certificate is listed with an `error` instead.

### `remove`

Stops trusting a stored certificate.

#### Parameters

<table><thead><tr><th width="150">Input</th><th>Description</th><th width="100">Type</th></tr></thead><tbody><tr><td><code>name</code></td><td>The name as shown by <code>list</code>.</td><td>string</td></tr></tbody></table>

#### Output

Returns `true`. An unknown name is an error that lists the names that exist.

## Good to know

### The words

* **Certificate**: the ID a server shows when a secure connection opens. It names the server and who issued the ID.
* **Self-signed**: the server issued its own ID. Normal for machines and PLCs.
* **Authority** (CA): whoever issued IDs for many servers. Trusting the authority trusts all of them.
* **Fingerprint**: the certificate's unique number. Two certificates with the same fingerprint are the same certificate, so it is safe to compare by eye with what the device shows.

### What trusting does, and does not do

Trusting a server does not switch security off. The connection stays encrypted, and any other certificate is still refused. `trustServer` accepts the server even when its certificate names another host than the address you dial, which is the usual case for a device reached by IP address.

The `tls` setting of a single connector instance or call rides on top of the list, with the same keys everywhere: `rejectUnauthorized`, `ca`, `cert`, `key`, `passphrase`. Setting `rejectUnauthorized: false` there accepts any certificate for that connection, trusted or not. A misspelt key is refused before any connection opens.

### When a change counts

Connectors that open TLS connections read the list each time they open one. A server trusted a moment ago is accepted by the next connection, without restarting or creating anything again. A connection already open stays as it is.

### Where the list lives

* **Platform**: under `/shared/certificates/pki`. Trusted servers sit in `trusted/certs`, authorities in `issuers/certs`, one `.pem` file each. A file placed there by hand counts as well.
* **Native agent**: in the `pki` folder next to the executable. Every agent keeps its own list.

The [OPC UA client](https://docs.heisenware.com/reference/functions/connectors/opc-ua-client.md) uses the same folders for its own certificates, and its `addServerCertificate` writes the same list. OPC UA servers do not speak TLS on `opc.tcp://`, so `trustServer` cannot fetch their certificate: use the certificate file the server offers.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.heisenware.com/reference/functions/connectors/trusted-certificates.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
