Nitroglycerin Pickle Machine

    TypeScript icon, indicating that this package has built-in type declarations

    4.2.5 • Public • Published

    acme-client CircleCI

    A simple and unopinionated ACME client.

    This module is written to handle communication with a Boulder/Let's Encrypt-style ACME API.


    acme-client API Style Node.js
    v4.x ACMEv2 Promise >= v10
    v3.x ACMEv2 Promise >= v8
    v2.x ACMEv2 Promise >= v4
    v1.x ACMEv1 callback >= v4

    Table of contents


    $ npm install acme-client


    const acme = require('acme-client');
    const accountPrivateKey = '<PEM encoded private key>';
    const client = new acme.Client({
        accountKey: accountPrivateKey

    Directory URLs;;;;;

    External account binding

    To enable external account binding when creating your ACME account, provide your KID and HMAC key to the client constructor.

    const client = new acme.Client({
        directoryUrl: '',
        accountKey: accountPrivateKey,
        externalAccountBinding: {
            kid: 'YOUR-EAB-KID',
            hmacKey: 'YOUR-EAB-HMAC-KEY'

    Specifying the account URL

    During the ACME account creation process, the server will check the supplied account key and either create a new account if the key is unused, or return the existing ACME account bound to that key.

    In some cases, for example with some EAB providers, this account creation step may be prohibited and might require you to manually specify the account URL beforehand. This can be done through accountUrl in the client constructor.

    const client = new acme.Client({
        accountKey: accountPrivateKey,
        accountUrl: ''

    You can fetch the clients current account URL, either after creating an account or supplying it through the constructor, using getAccountUrl():

    const myAccountUrl = client.getAccountUrl();


    For key pair generation and Certificate Signing Requests, acme-client uses node-forge, a pure JavaScript implementation of the TLS protocol.

    These utility methods are exposed through .forge.

    API documentation: docs/


    const privateKey = await acme.forge.createPrivateKey();
    const [certificateKey, certificateCsr] = await acme.forge.createCsr({
        commonName: '*',
        altNames: ['']

    Auto mode

    For convenience an auto() method is included in the client that takes a single config object. This method will handle the entire process of getting a certificate for one or multiple domains.

    A full example can be found at examples/auto.js.

    Documentation: docs/


    const autoOpts = {
        csr: '<PEM encoded CSR>',
        email: '',
        termsOfServiceAgreed: true,
        challengeCreateFn: async (authz, challenge, keyAuthorization) => {},
        challengeRemoveFn: async (authz, challenge, keyAuthorization) => {}
    const certificate = await;

    Challenge priority

    When ordering a certificate using auto mode, acme-client uses a priority list when selecting challenges to respond to. Its default value is ['http-01', 'dns-01'] which translates to "use http-01 if any challenges exist, otherwise fall back to dns-01".

    While most challenges can be validated using the method of your choosing, please note that wildcard certificates can only be validated through dns-01. More information regarding Let's Encrypt challenge types can be found here.

    To modify challenge priority, provide a list of challenge types in challengePriority:

        challengePriority: ['http-01', 'dns-01']

    Internal challenge verification

    When using auto mode, acme-client will first validate that challenges are satisfied internally before completing the challenge at the ACME provider. In some cases (firewalls, etc) this internal challenge verification might not be possible to complete.

    If internal challenge validation needs to travel through an HTTP proxy, see HTTP client defaults.

    To completely disable acme-clients internal challenge verification, enable skipChallengeVerification:

        skipChallengeVerification: true


    For more fine-grained control you can interact with the ACME API using the methods documented below.

    A full example can be found at examples/api.js.

    API documentation: docs/


    const account = await client.createAccount({
        termsOfServiceAgreed: true,
        contact: ['']
    const order = await client.createOrder({
        identifiers: [
            { type: 'dns', value: '' },
            { type: 'dns', value: '*' }

    HTTP client defaults

    This module uses axios when communicating with the ACME HTTP API, and exposes the client instance through .axios.

    For example, should you need to change the default axios configuration to route requests through an HTTP proxy, this can be achieved as follows:

    const acme = require('acme-client');
    acme.axios.defaults.proxy = {
        host: '',
        port: 9000

    A complete list of axios options and documentation can be found at:


    To get a better grasp of what acme-client is doing behind the scenes, you can either pass it a logger function, or enable debugging through an environment variable.

    Setting a logger function may for example be useful for passing messages on to another logging system, or just dumping them to the console.

    acme.setLogger((message) => {

    Debugging to the console can also be enabled through debug by setting an environment variable.

    DEBUG=acme-client node index.js




    npm i acme-client

    DownloadsWeekly Downloads






    Unpacked Size

    94.9 kB

    Total Files


    Last publish


    • nmorsman