{"id":26508837,"url":"https://github.com/adamkdean/zerossl","last_synced_at":"2025-10-05T08:24:46.561Z","repository":{"id":57405679,"uuid":"447966888","full_name":"adamkdean/zerossl","owner":"adamkdean","description":"ZeroSSL REST API wrapper","archived":false,"fork":false,"pushed_at":"2024-07-10T14:01:51.000Z","size":556,"stargazers_count":7,"open_issues_count":6,"forks_count":4,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-02-03T09:36:27.890Z","etag":null,"topics":["ssl","tls","zerossl"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adamkdean.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-01-14T12:53:28.000Z","updated_at":"2024-07-10T14:01:55.000Z","dependencies_parsed_at":"2024-07-10T16:38:07.488Z","dependency_job_id":null,"html_url":"https://github.com/adamkdean/zerossl","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adamkdean%2Fzerossl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adamkdean%2Fzerossl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adamkdean%2Fzerossl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adamkdean%2Fzerossl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adamkdean","download_url":"https://codeload.github.com/adamkdean/zerossl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244717364,"owners_count":20498284,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ssl","tls","zerossl"],"created_at":"2025-03-21T00:38:14.264Z","updated_at":"2025-10-05T08:24:46.459Z","avatar_url":"https://github.com/adamkdean.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ZeroSSL\n\nZeroSSL REST API wrapper based on the [ZeroSSL REST API documentation](https://zerossl.com/documentation/api/).\n\n![TypeScript](https://shields.io/badge/TypeScript-3178C6?logo=TypeScript\u0026logoColor=FFF) [![github stars](https://img.shields.io/github/stars/adamkdean/zerossl)](https://github.com/adamkdean/zerossl) [![npm version](https://img.shields.io/npm/v/zerossl)](https://www.npmjs.com/package/zerossl) [![npm downloads](https://img.shields.io/npm/dt/zerossl)](https://www.npmjs.com/package/zerossl) [![license](https://img.shields.io/npm/l/zerossl)](LICENSE.md)\n\n- [ZeroSSL](#zerossl)\n  - [Usage](#usage)\n    - [Initialization](#initialization)\n    - [Examples](#examples)\n      - [Get a list of certificate records](#get-a-list-of-certificate-records)\n      - [Get a certificate record](#get-a-certificate-record)\n    - [Create a certificate](#create-a-certificate)\n    - [Methods](#methods)\n    - [Types](#types)\n    - [Using a custom key pair](#using-a-custom-key-pair)\n  - [Tests](#tests)\n  - [Dependencies](#dependencies)\n  - [Disclaimer](#disclaimer)\n  - [License](#license)\n\n## Usage\n\nThis library provides a wrapper for the [ZeroSSL REST API](https://zerossl.com/documentation/api).\n\nIt has been recently developed and as such, may still require some refinement. Please feel free\nto feedback by opening an issue. Community contributions are appreciated.\n\n*Note: while this is written in TypeScript, it is transpiled to JavaScript and will work\nperfectly fine in a regular JavaScript project. Just ignore the TypeScript specific\nannotations in the examples below.*\n\n### Initialization\n\nCreating an intance of ZeroSSL is easy. Make sure to keep your API key secret.\n\n```typescript\nimport { ZeroSSL } from 'zerossl'\n\nconst accessKey = process.env.ZEROSSL_ACCESS_KEY || ''\nconst zerossl = new ZeroSSL({ accessKey })\n```\n\n### Examples\n\n#### Get a list of certificate records\n\n```typescript\nimport { ZeroSSL } from 'zerossl'\n\nconst accessKey = process.env.ZEROSSL_ACCESS_KEY || ''\nconst zerossl = new ZeroSSL({ accessKey })\n\nconst certificates = await zerossl.listCertificates()\n\ncertificates.results.forEach(certificate =\u003e {\n  console.log(certificate.id, certificate.status, certificate.common_name)\n})\n```\n\n#### Get a certificate record\n\n```typescript\nimport { ZeroSSL } from 'zerossl'\n\nconst accessKey = process.env.ZEROSSL_ACCESS_KEY || ''\nconst zerossl = new ZeroSSL({ accessKey })\n\nconst certificate = await zerossl.getCertificates('\u003cCERTIFICATE_ID\u003e')\n\nconsole.log(certificate)\n```\n\n### Create a certificate\n\n```typescript\nimport { ZeroSSL } from 'zerossl'\n\nconst accessKey = process.env.ZEROSSL_ACCESS_KEY || ''\nconst zerossl = new ZeroSSL({ accessKey })\n\n// Generate a keypair\nconst keyPair = zerossl.generateKeyPair()\n\n// Generate a CSR\nconst csrOptions = {\n  country: 'GB',\n  state: 'England',\n  locality: 'London',\n  organization: '',\n  organizationUnit: '',\n  email: '\u003cYOUR_EMAIL\u003e',\n  commonName: '\u003cYOUR_DOMAIN_NAME\u003e'\n}\nconst csr = zerossl.generateCSR(keyPair, csrOptions)\n\n// Create a certificate\nconst certificate = await zerossl.createCertificate({\n  csr: csr,\n  domains: ['\u003cYOUR_DOMAIN_NAME\u003e'],\n  validityDays: 90,\n  strictDomains: true\n})\n\n// Check it has been created\nconst checkResult = await zerossl.getCertificates(certificate.id)\nconsole.log(checkResult)\n\n// At this point, you should verify the domain\nconst verifyResult = await zerossl.verifyDomains(certificate.id, { validation_method: 'HTTP_CSR_HASH' })\nconsole.log(verifyResult)\n\n// Wait for ZeroSSL to issue certificate (anywhere up to 10 mins apparently)\n```\n\nFor more examples, see the integration tests.\n\nFor an example of a basic HTTP verification server, see [adamkdean/zerossl-verify](https://github.com/adamkdean/zerossl-verify).\n\n### Methods\n\nThe available methods mostly match those of the API, though there are a few additional methods.\n\n```typescript\npublic async createCertificate(options: CreateCertificateOptions): Promise\u003cCertificateRecord\u003e\npublic async verifyDomains(id: string, options: VerifyDomainOptions): Promise\u003cCertificateRecord\u003e\npublic async downloadCertificate(id: string): Promise\u003cCertificate\u003e\npublic async getCertificate(id: string): Promise\u003cCertificateRecord\u003e\npublic async listCertificates(options?: ListCertificateOptions): Promise\u003cCertificateList\u003e\npublic async verificationStatus(id: string): Promise\u003cVerificationStatus\u003e\npublic async resendVerification(id: string): Promise\u003cboolean\u003e\npublic async cancelCertificate(id: string): Promise\u003cboolean\u003e\npublic async revokeCertificate(id: string): Promise\u003cboolean\u003e\npublic async validateCSR(csr: string): Promise\u003cCertificateSigningRequestValidationResult\u003e\npublic generateKeyPair(bits = 2048): KeyPair\npublic generateCSR(keypair: KeyPair, options: CertificateSigningRequestOptions): string\n```\n\n### Error Return\n\nIf an error occurs in your request, we will trigger a throw error detailing the error name, error code, error type and error status code through an object as you can see below:\n\n```json\n{\n    \"message\": \"An error has occurred\",\n    \"code\": \"000\",\n    \"type\": \"error_example\",\n    \"status\" : 400\n}\n```\n\n### Types\n\nYou can access all the types used by this library by importing them from `zerossl/lib/types`, e.g.\n\n```typescript\nimport { CertificateRecord } from 'zerossl/lib/types'\n```\n\n### Using a custom key pair\n\nTo use a custom key pair, you must ensure the private key is an RSA key in PEM format, and that the public key is in PEM format too.\n\nTo generate an RSA key pair, and convert the public key to PEM:\n\n```sh\nssh-keygen -m pem -t rsa -b 4096\nssh-keygen -f \u003cPUBLIC_KEY_FILE\u003e -e -m pem \u003e \u003cPUBLIC_KEY_FILE\u003e\n```\n\nYou then simply need to create a KeyPair object:\n\n```typescript\nconst keyPair = {\n  privateKey: '\u003cPRIVATE_KEY_PEM\u003e',\n  publicKey: '\u003cPUBLIC_KEY_PEM\u003e'\n}\n\nzerossl.generateCSR(keyPair, { ... })\n```\n\n## Tests\n\nWhile I have endeavoured to write tests for this library, I have not\nbeen able to comprehensively implement them. Most functionality has\nbeen tested but as the documentation provided by ZeroSSL is quite\nsparse, there may be edge cases that have not been accounted for.\n\nCommunity contributions are welcome.\n\n## Dependencies\n\nThis library only has two top-level dependencies: `node-forge` and `superagent`.\n\n## Disclaimer\n\nThis library is a community open source project. There is no connection\nwith ZeroSSL or Stack Holdings GmbH. The term ZeroSSL/zerossl is recognised\nas ZeroSSL™, a trademark of Stack Holdings GmbH in the USA, EU \u0026 UK and\nthis library is provided in good faith as a community open source project.\n\n## License\n\nMIT License\n\nCopyright (c) 2022 Adam K Dean \u003cadamkdean@googlemail.com\u003e\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadamkdean%2Fzerossl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadamkdean%2Fzerossl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadamkdean%2Fzerossl/lists"}