> ## Documentation Index > Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # TLS Certificates > Learn how ngrok manages TLS certificates automatically, or how you can manually configure them yourself. ngrok automatically handles TLS (SSL) certificate management and termination for you. There is typically nothing to set up, configure, or manage. You can manage TLS certificates on your [ngrok dashboard](https://dashboard.ngrok.com/tls-certs) or via the [ngrok API](#api). ## Overview TLS certificates are a tuple of a private key and certificate that are presented by the ngrok cloud service during a TLS handshakes to terminate TLS connections to [HTTPS endpoints](/gateway/http) and [TLS endpoints](/gateway/tls). TLS certificates are attached to [domains](/gateway/domains/) for termination of TLS connections to endpoints whose URLs match that domain. ngrok can automatically provision certificates for you or you can upload your own. See the [TLS Termination](/gateway/tls-termination/) documentation for details on how and when ngrok terminates TLS connections. ## Certificate selection When TLS connections to an endpoint are terminated, ngrok uses the TLS Certificate attached to the [domain](/gateway/domains) matching the endpoint's URL for termination. Each [domain](/gateway/domains/) has an attached TLS certificate that is referenced by its [`certificate_id` field](/api-reference/reserveddomains/get#response-certificate-id). If the domain object does reference any certificate, or if there is no matching domain object for an endpoint's URL, ngrok selects its own TLS certificate for termination. You may override the certificate used for TLS termination by explicitly terminating TLS yourself with the [`terminate-tls` Traffic Policy action](/traffic-policy/actions/terminate-tls/). ## Certificate provisioning Whenever you create a [domain](/gateway/domains/) you choose how a TLS certificate will be provisioned. Either: * [Automatic TLS certificates](#automated) (default) - ngrok automatically provisions a TLS certificate from an ACME provider like Let's Encrypt. * [Bring your own TLS certificates](#custom) - Upload your own TLS certificate It is recommended that you choose automatic TLS certificates unless you have special requirements. ## Automatic provisioning When you choose automatic TLS certificate management for a domain (this is the default), ngrok automatically provisions **and renews** TLS certificates from an ACME-compliant certificate authority like Let's Encrypt. ngrok uses an HTTP01 challenge for TLS certificate provisioning of most domains. When you create a [wildcard domain](#wildcard-domains) ngrok uses a DNS01 challenge instead. ngrok is a [Let's Encrypt sponsor](https://letsencrypt.org/sponsors/). ### Status TLS certificates are provisioned asynchronously. Depending on the speed of the ACME certificate authority, it can take anywhere between a few seconds to 10 minutes for your certificate to be provisioned. The domain's `certificate_management_status` field on the [TLS Certificate API Resource](/api-reference/tlscertificates/list/) contains the status of the provisioning job. ### Bring your own domain When you [bring your own domain](/gateway/domains/#branded-domains) (such as `api.your-domain.com`) you must create a CNAME DNS record in your DNS provider. Certificate provisioning will not begin until your create this CNAME DNS record. ### Wildcard domains When you bring your own wildcard domain (such as `*.app.example.com`), ngrok uses a DNS01 challenge for TLS certificate provisioning which means that you must create two CNAME records when creating branded wildcard domains instead of just one. For example, if your domain is `*.app.example.com`, you will be required to create the following two CNAME records: * `*.app.example.com` * `_acme-challenge.app.example.com` Certificate provisioning will not begin until you have created both DNS records. ### Private keys When using automatic TLS certificates, ngrok generates a private key for your domain and encrypts it at rest with [NaCL](https://nacl.cr.yp.to/). When you configure a domain to use automated certificates, you may electively choose whether ngrok will create an ECDSA private key (the default) or RSA private key. If you choose an RSA private key, it is created with a size of 4096 bits. ## Bring your own certificates You may upload your own TLS certificates if you don't want to use the TLS certificates that ngrok automatically provisions for you. Uploading your own certificates may be the right choice if you are issuing certificates from your own certificate authority or if you are using an EV certificate. To bring your own TLS certificate, upload a [certificate bundle](#certificate-bundles) and a [private key](#private-keys). Keep in mind that after you create your TLS certificate, you must attach it to one or more domains before it will be used for termination. When working with the API, this is done by updating the `certificate_id` property of the [Domain API Resource](/api-reference/reserveddomains/get#response-certificate-id). Unlike automatic TLS certificates, when you are using custom TLS certificates, you are responsible for managing the renewal and rotation of new certificates. ### Certificate bundles When uploading your own TLS certificates to ngrok, you are expected to provide a certificate bundle of all certificates necessary to establish a chain of trust to a trusted root certificate authority. Many TLS certificate vendors will provide you with a constructed certificate bundle, but some will return the leaf certificate and the intermediate certificates separately and you must concatenate them to construct the bundle yourself. This is the `certificate_pem` field in the [TLS Certificate Create API](/api-reference/tlscertificates/list/). Certificate bundles are a series of PEM-encoded X.509 certificates that have been concatenated together. **The order of this bundle is significant.** The first certificate in the bundle must be the leaf certificate. The leaf certificate is the one which is signed for your domain and [the private key](#private-keys) you will upload. After the leaf certificate are the intermediates certificates, if any. Each intermediate certificate signs the certificate preceding it in the bundle. As an example, the first intermediate will sign the leaf, and that signature is part of the leaf certificate itself. The final certificate will be signed by the root certificate authority. You may also included the root certificate in the bundle as well, but it is not necessary or common practice to do so. A certificate bundle will look like the following: ```pem theme={null} -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- ``` ### Private keys ngrok accepts the following formats for the private key of an uploaded TLS certificate. This is the `private_key_pem` field in the [TLS Certificate Create API](/api-reference/tlscertificates/create/). * RSA, in either PKCS#1 or PKCS#8 form. * ECDSA, in either SEC 1 or PKCS#8 form. * Ed25519, in PKCS#8 form. Regardless of the format you choose, the private key must be formatted as ASN.1 DER, encoded as PEM. ngrok does not accept any private keys that are encrypted (for example, with DES). ngrok encrypts your uploaded private keys at rest with [NaCL](https://nacl.cr.yp.to/). ## API TLS certificates are managed programmatically via: * [`/tls_certificates` API Resource](/api-reference/tlscertificates/get) ## Pricing TLS certificates are available on all plans. Bringing your own certificates is available on the Pay-as-you-go plan.