> 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/guides/integration-management/how-to-use-acme-in-frends.md).

# How to use ACME in Frends

Implementing the automatic certificate management.

Certificate lifetimes are shrinking across the industry, and manually replacing Agent certificates is becoming a recurring burden for platform operations. To remove that manual work, Frends supports the ACME protocol (RFC 8555) for automated certificate management. With ACME, Frends can request a TLS certificate from a certificate authority such as Let's Encrypt or ZeroSSL, prove that you control the domain, and then install the certificate on the Agents in an Agent Group without anyone touching the machines or restarting the Agents.

The feature was introduced in Frends 6.4 and is managed entirely through the Frends Platform API. There is no user interface for it, so everything described in this guide is done by calling the API endpoints.

## Prerequisites

Before you start, make sure the environment is ready for ACME.

You need a Frends installation running version 6.4 or later, with the message bus and the Configuration Database available, since certificates are stored in the Configuration Database and distributed to Agents over the message bus. You also need at least one Agent Group with a registered Agent, because every certificate is scoped to an Agent Group and that group is the distribution target for the certificate.

Certificate private keys are distributed to Agents over the message bus, so 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 use an `amqps://` connection string rather than a plaintext one.

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

{% hint style="info" %}
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.
{% endhint %}

Finally, decide how you will prove domain ownership. The `http-01` challenge requires the Agent to be reachable from the internet on port 80, while the DNS challenges require you to be able to publish TXT records in the domain's DNS zone.

## Understanding the ACME Building Blocks

ACME in Frends is built from three things: accounts, orders, and certificates. Understanding how they relate makes the flow much easier to follow.

An ACME account is a registration with a certificate authority. Accounts are installation-global, which means they are not tied to any Agent Group or domain, and the same account can be reused for orders in different groups. Frends ships with a provider catalog that includes Let's Encrypt production, Let's Encrypt staging, ZeroSSL, and a custom directory URL option. ZeroSSL requires External Account Binding (EAB), which you supply as a key ID and an HMAC key.

An ACME order is a single request for a certificate. An order always references an ACME account and an Agent Group, and it carries the domain, the challenge type, and an optional certificate name. The order is what progresses through the challenge, validation, and finalization steps, and it ends up producing a certificate.

A certificate is the result of a successful order. Issued certificates get the purpose `HttpsServer` and are stored as Agent Group certificates. Uploaded certificates and ACME-issued certificates behave the same way once they exist: they are created inactive, you activate them explicitly, and then you distribute them to the Agents in the group.

## Checking the Available Providers

Start by listing the providers your installation supports. The provider catalog tells you which certificate authorities you can register an account with, and whether the provider requires EAB.

Call `GET /api/v1/acme/providers` to retrieve the catalog. The built-in entries are `LetsEncrypt`, `LetsEncryptStaging`, `ZeroSSL`, and `Custom`. The `Custom` option lets you point Frends at any ACME directory URL, which is useful for testing or for an internal certificate authority.

## Creating an ACME Account

With the provider chosen, register an account with it. Create the account by calling `POST /api/v1/acme/accounts` with the provider name and an email address.

```
{
  "provider": "LetsEncrypt",
  "email": "platform-ops@example.com"
}
```

The email is optional. If you omit it, Frends sends no contact information to the certificate authority, so leave the field out rather than sending an empty string.

If you are registering with ZeroSSL, include the EAB credentials in the same request. Frends forwards the EAB values to the authority for every provider, and the catalog's `RequiresEab` flag tells you when they are mandatory.

```
{
  "provider": "ZeroSSL",
  "email": "platform-ops@example.com",
  "eabKeyId": "<your key id>",
  "eabHmacKey": "<your hmac key>"
}
```

For a custom certificate authority, use the `Custom` provider and supply the directory URL.

```
{
  "provider": "Custom",
  "customDirectoryUrl": "https://acme.example.com/dir",
  "email": "platform-ops@example.com"
}
```

You can list your accounts with `GET /api/v1/acme/accounts` and inspect a single account with `GET /api/v1/acme/accounts/{accountGuid}`. Deleting an account is done with `DELETE /api/v1/acme/accounts/{accountGuid}`. An account cannot be deleted while a `dns-persist-01` order with a still-active certificate still references it; in that case the API returns a 409 and you need to remove the certificate first.

## Creating an Order

An order is where the actual certificate request begins. Create it with `POST /api/v1/acme/orders`, passing the account, the target Agent Group, the domain, and the challenge type.

```
{
  "accountGuid": "<account guid>",
  "agentGroupName": "ProductionAgents",
  "domain": "agents.example.com",
  "challengeType": "http-01"
}
```

You can optionally include `certificateName` to control the name of the resulting certificate. If you leave it out, Frends derives the name from the domain by replacing dots and hyphens with underscores. The order response contains the order GUID, the current status, and, for DNS challenges, the TXT record details you need to publish.

## Completing the Challenge

The challenge type determines what you have to do before the certificate authority will issue the certificate. Frends supports three types, and the right choice depends on your infrastructure and how much automation you want.

#### HTTP-01

The `http-01` challenge is the most automated option. When you validate the order, Frends sends the challenge to the Agents in the group over the message bus, and the Agents serve it from the well-known endpoint `/.well-known/acme-challenge/{token}`. The certificate authority then fetches that URL to confirm you control the domain.

Because the authority has to reach the Agent directly, the Agent must be reachable from the internet on port 80, and at least one Agent in the group must be online to confirm delivery of the challenge. If no Agent is online, validation fails with a clear error.

#### DNS-01

The `dns-01` challenge works without any inbound access to the Agents. When you create the order, the API response returns the TXT record name and value you need to publish. You add the record to your DNS zone, and then validate the order so the authority can look it up.

The record name stays the same across orders, but the value changes for every order, so each renewal needs a fresh TXT record. This is why `dns-01` certificates are the only ones that cannot renew fully automatically.

#### DNS-PERSIST-01

The `dns-persist-01` challenge is a persistent variant of the DNS approach. Instead of a per-order token, the TXT record is derived from the issuer domain and the account URI, so it stays the same across orders and only needs to be set up once. That makes it a good fit for environments where you want the automation of `http-01` but cannot expose the Agents to inbound traffic.

When you create a `dns-persist-01` order, the response contains a TXT record in the format `<issuer>; accounturi=<uri>`. If you are using a custom provider, include `issuerDomainName` in the order request, otherwise the API returns a 400 because a custom provider has no issuer domain in the catalog.

Note that wildcard domains are supported with `dns-01` and `dns-persist-01`, but never with `http-01`. Attempting a wildcard order with `http-01` is rejected with a message directing you to one of the DNS challenges.

## Validating and Finalizing the Order

Once the challenge is in place, validate the order by calling `POST /api/v1/acme/orders/{orderGuid}/validate`. Poll the certificate authority until the challenge completes, and any provider error is recorded on the order and returned by the API.

When validation succeeds, finalize the order with `POST /api/v1/acme/orders/{orderGuid}/finalize`. Finalization builds the certificate and stores it as an ACME-sourced certificate for the Agent Group, and the response gives you the `certificateGuid`.

You can follow the progress of your orders at any time with `GET /api/v1/acme/orders`, optionally filtered by status, or inspect a single order with `GET /api/v1/acme/orders/{orderGuid}`.

## Activating and Distributing the Certificate

A newly issued certificate is not yet in use. To put it into service, activate it with `POST /api/v1/certificates/{certificateGuid}/activate`. Activating a certificate also distributes it to the Agents in the group, so this single call is what brings the certificate into use.

Activation supersedes the previously active certificate with the same name in the group, and the newly activated certificate is distributed to the group's Agents. 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. The distribute response 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, and any new Agent that registers into the group automatically receives the group's active certificates.

If distribution fails after activation, you can re-drive it with the explicit `POST /api/v1/certificates/{certificateGuid}/distribute` endpoint instead of activating the certificate again.

## 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.

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 in `GET /api/v1/acme/orders`, and you publish the new TXT record and complete the order yourself.

The renewal behaviour is controlled by the `AcmeRenewal` settings in the Management configuration, where `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.

## Managing Certificates Alongside ACME

ACME is one way to get certificates into Frends; manual upload is the other. Uploading a `.pfx` file with `POST /api/v1/certificates` is useful for certificates issued outside Frends, such as client certificates or certificates from an internal authority.

Both routes end in the same place. Every certificate is Agent Group scoped, there is no agent-level scope, and both uploaded and ACME-issued certificates are created inactive and then activated and distributed in the same way. You can list certificates with `GET /api/v1/certificates`, inspect one with `GET /api/v1/certificates/{certificateGuid}`, check which deployed Process versions depend on it with `GET /api/v1/certificates/{certificateGuid}/usages`, and remove it with `DELETE /api/v1/certificates/{certificateGuid}`. 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.


---

# 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/guides/integration-management/how-to-use-acme-in-frends.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.
