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

# ACME

Details for Automatic Certificate Management.

ACME, the Automatic Certificate Management Environment, is the protocol defined in RFC 8555 that lets a certificate authority issue and validate TLS certificates without a person doing the work by hand. Frends uses ACME to obtain, renew, and deliver the certificates its Agents use, so keeping them valid becomes a background concern instead of a recurring manual task. This matters because certificate lifetimes keep shrinking: industry-wide validity is heading toward 47 days by 2029, and Let's Encrypt is already moving to 45-day certificates in 2026, which turns manual certificate handling into a continuous and error-prone chore.

ACME certificate management was introduced in Frends 6.4 and is managed entirely through the Frends Platform API; there is no user interface for it.

## What ACME certificate management is

ACME certificate management is Frends' built-in way of handling the HTTPS certificates that Agents use. Rather than a file placed on each server and replaced by hand, a certificate is a managed resource of the platform: requested from a certificate authority, kept with the Agent Group it belongs to, and made available to the Agents that need it. It is built on the same protocol certificate authorities use to issue and validate certificates automatically, and it is managed through the Frends Platform API, so certificate work can be scripted and folded into existing automation.

The feature is provided alongside the platform's existing certificate handling. Certificates from a non-ACME source can still be uploaded and managed through the same methods as before, so the feature covers both automated and manual needs.

Certificates are stored in the Configuration Database and distributed to Agents over the message bus. Because certificate private keys travel over that bus, the bus connection itself should be secured with TLS. Frends logs an error at startup when the internal bus URI is plaintext `amqp://`, and the `MessageBus.RequireTls` setting on Management Web and the Log service, together with `RequireTlsForMessageBus` on the Agent, makes the component refuse to start outright. Both settings default to `false` in 6.4, but the default is planned to change to `true` in a later major version, so an `amqps://` connection string should be used rather than a plaintext one.

A working setup needs a Frends installation running version 6.4 or later, with the message bus and the Configuration Database available, and at least one Agent Group with a registered Agent. Every certificate is scoped to an Agent Group, and that group is the distribution target for the certificate.

<figure><img src="https://3198802258-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1H5SQ92uIfBOYNIeoUAc%2Fuploads%2FcZWia1Kj0KjJNiCAJmsT%2Fimage.png?alt=media&amp;token=5d0e2cfe-2813-4d08-981c-ac41a5ed32e4" alt=""><figcaption><p>ACME endpoints in Frends Platform API.</p></figcaption></figure>

Certificates are the managed resources that Agents actually use. Every certificate is Agent Group scoped, there is no agent-level scope, and an Agent Group can serve several certificates at the same time.

### Certificate names and purposes

Every certificate has a name and a purpose. The name is the identifier you use to reference the certificate later, and it must match the pattern `^[A-Za-z_åäöÅÄÖ][A-Za-z0-9_åäöÅÄÖ]{0,63}$`, which makes it a valid `#cert.<name>` segment. A name is case-insensitively unique among the active certificates of its scope.

The purpose describes what the certificate is for. `HttpsServer` certificates are served by the Agent's HTTPS listener. `ClientAuthentication` certificates are used when a Process calls an external endpoint that requires mutual TLS. `ClientCertificateIssuer` certificates are issuer certificates used to validate the caller's certificate chain for HTTP triggers that authenticate with certificates. A name has exactly one purpose, and the purpose is validated against the certificate material: `HttpsServer` and `ClientAuthentication` require a private key and, when an extended key usage extension is present, the matching `serverAuth` or `clientAuth` usage, while `ClientCertificateIssuer` is certificate-only and must be a certificate authority when basic constraints are present.

### Certificate fields

A certificate exposes its name, purpose, whether it carries a private key, whether it is Frends-managed, its thumbprint, subject, issuer, validity period, source, and active status, together with the per-Agent install status of the distribution. No key material is ever returned.

### Activation and distribution

A newly issued or uploaded certificate is created inactive and is not yet in use. Activation brings it into service and distributes it to the Agents in the group in the same operation. Activation supersedes the previously active certificate with the same name in the group; certificates with different names can be active at the same time, so an Agent Group can serve several certificates simultaneously.

Distribution sends the certificate to the Agents over the secured message bus. Agents install it into their certificate store on both Windows and Linux and hot-swap the HTTPS certificate without a restart, so there is no downtime when a certificate is replaced. Distribution reports which Agents were reached and which were skipped, for example because they were offline; skipped Agents pick up the certificate on their next heartbeat. Distribution can also be re-driven on its own, without activating the certificate again.

### Delivering certificates to Agents

Certificate delivery happens over the message bus rather than by embedding certificate material in the initial configuration payload. When a new Agent registers into an Agent Group, it receives the group's active certificates automatically right after its initial configuration is delivered, without waiting for a manual distribute call. A group-wide full sync re-sends the active certificates to every Agent, and delivery is idempotent on the Agent.

### Manual certificates alongside ACME

ACME is one way to get certificates into Frends; manual upload is the other. Uploading a `.pfx` file is useful for certificates issued outside Frends, such as client certificates or certificates from an internal authority. The upload accepts `.pfx`, `.pem`, `.p12`, `.crt`, and `.cer` files with an optional password, and PEM material is normalized to PFX for uniform storage.

Both routes end in the same place. Every certificate is Agent Group scoped, both uploaded and ACME-issued certificates are created inactive, and both are activated and distributed in the same way. A certificate that is still referenced by a deployed Process version cannot be deleted without a replacement, and the API returns a 409 in that case. Certificate responses expose metadata only; certificate blobs are never returned.

### Referencing certificates in Processes

Once a certificate is active in the Agent Group, a Process can reference it by name using the `#cert` syntax, in the same spirit as `#env` references. The general form is `#cert.<name>.<property>`, and the reference is resolved on the Agent when the Process starts, so tasks can load the certificate from the store by thumbprint without hard-coding a value that changes on every rotation.

The available properties are listed below. No key material is ever exposed; tasks use the thumbprint together with the store.

<table data-search="false"><thead><tr><th>Property</th><th>What it provides</th></tr></thead><tbody><tr><td><code>name</code></td><td>The certificate's name</td></tr><tr><td><code>thumbprint</code></td><td>The certificate thumbprint</td></tr><tr><td><code>subject</code></td><td>The certificate subject</td></tr><tr><td><code>issuer</code></td><td>The certificate issuer</td></tr><tr><td><code>notBefore</code></td><td>The start of the validity period</td></tr><tr><td><code>notAfter</code></td><td>The end of the validity period</td></tr><tr><td><code>purpose</code></td><td>The certificate purpose</td></tr><tr><td><code>storeName</code></td><td>The store name, <code>My</code></td></tr><tr><td><code>storeLocation</code></td><td>The store location, <code>CurrentUser</code></td></tr><tr><td><code>hasPrivateKey</code></td><td>Whether the certificate carries a private key</td></tr></tbody></table>

References are case-insensitive, like `#env`. If the name is not available on the Agent, the Process fails at the reference with the message `Certificate '<name>' is not available on this agent`. A typical reference in a task parameter or expression looks like `#cert.clientauth_test.thumbprint`, and you can combine it with surrounding text, for example when building a header value such as `Bearer #cert.clientauth_test.thumbprint`.

Frends validates certificate references so problems surface before a Process reaches production. At deployment, the referenced names must exist as active, group-scoped certificates in the target Agent Group. If they do not, deployment is blocked and the error names both the Agent Group and the missing certificates, so you know exactly what to upload and activate. This check is skipped for the Development version switch, just like environment variables. The Process editor helps you get the reference right in the first place: typing `#cert.` suggests the certificate names available in the Agent Group, and after a known name it suggests the valid properties.

## Automatic renewal

Frends renews ACME certificates automatically. A background service sweeps the active ACME-sourced certificates and renews each one once it has passed a configured share of its own validity period, so the renewal point scales with the certificate lifetime rather than following a fixed calendar schedule. Each certificate is handled independently, so one failing renewal never blocks the rest, and failures are recorded on the order and returned by the API.

### Renewal behaviour by challenge type

How much of the flow is automatic depends on the challenge type. Certificates issued with `http-01` and `dns-persist-01` renew end to end without any manual action, because the challenge can be completed without a new DNS record. Certificates issued with `dns-01` cannot renew unattended, since each renewal needs a fresh TXT value; instead, Frends creates a new order that appears as a pending action, and the new TXT record must be published to complete it.

### Renewal settings

The renewal behaviour is controlled by the `AcmeRenewal` settings in the Management configuration. `CheckIntervalHours` sets how often the sweep runs, and `RenewAtLifetimeFraction` sets the share of the lifetime after which a certificate becomes due. Setting `CheckIntervalHours` to `0` disables the renewal runner.

## Authorization and the FrendsOps boundary

Your API caller must have the permissions to the Frends Platform API Admin activity, and for operations that target a specific Agent Group you also need environment admin rights for that group.

Agent Groups operated by Frends are a special case. HTTPS certificates and ACME orders for Cloud Agent Groups are managed by Frends Operations, and a regular caller receives a 403 if they try to create, validate, or finalize an order for such an Agent Group, or to upload, activate, distribute, or delete an `HttpsServer` certificate in it. Frends-managed ACME accounts are likewise restricted: only Frends operations can create or delete them. Client authentication and client certificate issuer certificates stay customer-managed even in a Frends-operated group.

Every refused attempt at the FrendsOps boundary is recorded in the audit log with a failure outcome, even though the mutation itself is blocked. The `AcmeOrders:AllowFrendsOpsWildcardOrders` setting controls whether Frends operations may order wildcard certificates for a Frends-operated group; automatic renewals have no caller and are not subject to this gate.

## Protection of certificate key material

Certificate private keys and the ACME account key are protected both where they are stored and while they move between components.

### Encryption at rest

Certificate and ACME key material is encrypted at the application level with ASP.NET Core Data Protection, so it is unreadable without the key-encryption key even to someone with direct database access. The Data Protection key ring is stored in the Configuration Database and shared by all Management Web replicas, and the key-encryption key is an X.509 certificate supplied from a Windows certificate store thumbprint, a PFX or PEM file, or a Key Vault secret. Encryption is controlled by `DataProtection:KeyProtection`, which is either `Certificate` or `None`, with `DataProtection:Certificate` naming the key source. When the section is absent, `None` is the default: key material stays unencrypted and every instance logs a startup warning, and once a key-encryption key is configured the existing rows are encrypted automatically at startup. The key-encryption key must be backed up, because losing it makes the encrypted rows unreadable.

### TLS in transit

Certificates are delivered to Agents over the configuration message bus, so that bus carries key material and should be secured with TLS. A plaintext `amqp://` internal bus URI is treated as a problem: Management, the Agent, and the Log service log an error at startup, and the `MessageBus.RequireTls` setting on Management Web and the Log service, together with `RequireTlsForMessageBus` on the Agent, makes the component refuse to start.

Both settings default to `false` in 6.4, but the default is planned to change to `true` in a later major version, so an `amqps://` connection string should be used going forward.

## Configuration settings

The feature is configured through the Management configuration and the Agent configuration rather than through a user interface.

| Setting                                   | Type    | Component                      | Effect                                                                                            |
| ----------------------------------------- | ------- | ------------------------------ | ------------------------------------------------------------------------------------------------- |
| `MessageBus.RequireTls`                   | Boolean | Management Web and Log service | Refuses to start ACME when set to `false`                                                         |
| `RequireTlsForMessageBus`                 | Boolean | Agent                          | Refuses to start ACME when set to `false`                                                         |
| `AcmeRenewal.CheckIntervalHours`          | Number  | Management                     | How often the renewal sweep runs; `0` disables it                                                 |
| `AcmeRenewal.RenewAtLifetimeFraction`     | Number  | Management                     | Share of the certificate lifetime after which renewal is due                                      |
| `AcmeOrders.AllowFrendsOpsWildcardOrders` | Boolean | Management                     | Whether Frends Operations may order wildcard certificates for a Frends-operated Cloud Agent Group |


---

# 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.frends.com/reference/frends-platform-api/acme.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.
