---
title: "SSL certificates — API v1 and MCP | Nodea documentation"
description: "Reference of the SSL certificates module: REST API v1 endpoints (list, details), infra:read scope, products account permission, renewal states, DCV instructions and MCP tools."
url: "https://nodea.io/en/api-docs/ssl-certificates"
lang: "en"
updated: "2026-10-14"
---

# SSL certificates — API v1 and MCP | Nodea documentation

> Reference of the SSL certificates module — read-only API v1 endpoints (list, details), infra:read scope, statuses, renewals after the period is paid, domain validation instructions and MCP tools.

The **SSL certificates** module gives read access to the commercial SSL certificates of a customer account (issued by Sectigo through GoGetSSL): order status, product, term, validity dates, renewal state and — while the order is in progress — the domain control validation (DCV) instructions. Ordering, reissuing, changing the validation method and downloading the files (certificate, CA bundle, private key) happen in the panel (/app/ssl-certificates), not through the API. This document describes the REST API v1 layer (/api/v1/ssl-certificates) and the MCP tools of the module.

## Authentication and scopes

API v1 authenticates with a Passport personal access token in the Authorization: Bearer \<token\> header. The module is read-only:

- infra:read — list and details of certificates.

The module has no Pennant flag. Rate limit: throttle:api-v1 = 240/min per token user. In MCP every tool also needs the transport scope mcp:use.

## Customer account, ownership and visibility

Certificates belong to a **customer account** (see [Customer accounts](https://nodea.io/en/api-docs/accounts)). A request acts in the current account (token pin → X-Account-Id header → default account). Besides the token scope the account permission products is required. A certificate of another account returns 404 — its existence is never confirmed.

**Security:** responses never contain the private key, the CSR or the certificate body (PEM) — files are downloaded in the panel only, and every private key download is logged.

## Lifecycle and payment

A certificate is ordered from the issuer only after it is paid (account balance or pro-forma). The renewal at the issuer is ordered automatically once the billing period covering the expiry date is **paid**. A multi-year subscription (subscription\_ends\_at later than the certificate validity) needs a free reissue in the panel.

## API v1 — endpoints

MethodPathScopeDescriptionGET/api/v1/ssl-certificatesinfra:readCertificates of the current account (newest first). Parameters: status (optional filter), per\_page (1–100, default 20), page. GET/api/v1/ssl-certificates/{id}infra:readDetails of one certificate.

### Response — certificate

- id, common\_name, san\_domains (list), service\_id (billing service, nullable), created\_at.
- status — awaiting\_payment | pending\_submission | processing | active | expired | cancelled | rejected | failed | awaiting\_configuration.
- product — { id, name, validation (dv|ov|ev), is\_wildcard } or null.
- period\_years (1–3), dcv\_method — dns | http | https | email.
- dcv — only in the processing status, otherwise null: { dns?: { name, type (CNAME|TXT), value, record }, http?/https?: { link, filename, content }, email?: string, san?: \[{ name, method, status }\] }.
- valid\_from, valid\_until, subscription\_ends\_at (ISO8601, nullable), days\_until\_expiry (int|null).
- renewal — none | paid (renewed automatically) | unpaid (waiting for the period to be paid) | reissue (multi-year subscription — reissue) | renewed (renewal in progress) | manual.
- certificate\_available (bool) — whether the certificate is ready to download in the panel.

The list returns { data: \[...\], meta: { current\_page, per\_page, total, last\_page } }, details { data: {...} }.

### Error codes

- 401 — missing/invalid token.
- 403 — missing infra:read scope, no account context (no\_account\_context) or missing products permission (account\_permission\_denied).
- 404 — unknown certificate or a certificate outside the current account.
- 422 — invalid status / per\_page.

## Examples — API

### Certificates in validation

curl -s "https://app.nodea.io/api/v1/ssl-certificates?status=processing" \\ -H "Authorization: Bearer $NODEA\_TOKEN" \\ -H "Accept: application/json"

### Certificate details

curl -s https://app.nodea.io/api/v1/ssl-certificates/42 \\ -H "Authorization: Bearer $NODEA\_TOKEN" \\ -H "Accept: application/json"

## MCP — tools

MCP tools share the authentication, scope and account model with API v1. A certificate outside the current account returns the same error as a missing one.

ToolScopeModeDescriptionssl-certificates-listinfra:readread-onlyCertificates of the current account; status (optional), page, per\_page (max 50). Fields as in the API response, plus pagination meta. ssl-certificate-getinfra:readread-onlyOne certificate with the validation instructions; id (required).

### Example — MCP (JSON-RPC)

{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "ssl-certificate-get", "arguments": { "id": 42 } } }

## Related

- [Dedicated servers — API v1 and MCP | Nodea Documentation](https://nodea.io/en/api-docs/dedicated-servers)
- [Domains — API v1 and MCP | Nodea Documentation](https://nodea.io/en/api-docs/domains)
- [Billing — API v1 and MCP | Nodea Documentation](https://nodea.io/en/api-docs/billing)

---

Languages: [pl](https://nodea.pl/pl/dokumentacja-api/ssl-certificates.md)  
Site index: [llms.txt](https://nodea.io/en/llms.txt)