How do I add an SSL/TLS certificate?

Requires Pro

Quick answer

Open the Certificates module, click “Add Certificate”, enter the Common Name (CN), and save. Only Common Name and status (default Active) are required. Add the issuer, valid from/to, key type/size, fingerprint, and the auto-renew option. The list is automatically sorted by Valid To — the certificate expiring soonest appears at the top.

Prerequisites

Required role Administrator, Manager, or Technician

— any signed-in user with write access to Certificates. Via the API: token scope write. Deletion is reserved for administrators.

The Certificates module is part of the Pro tier (feature certificates). In lower tiers, the menu item is hidden; an API call is rejected with 403.

Instructions

GUI (web interface)

1. Open the “Certificates” module. Select Certificates in the left-hand navigation. You’ll see the list of all certificates, sorted by expiry date. The “Add Certificate” button sits at the top right.

   Screenshot pending zertifikate-erfassen-01 Certificate list with the 'Add Certificate' button at the top right

   The certificate overview with the 'Add Certificate' button.

2. Fill out the form. In the “Add Certificate” dialog, fill in at least the Common Name (CN) and choose a status. Further fields:

   • Issuer, Valid From, Valid To
   • Key Type (e.g. RSA, EC), Key Size (e.g. 2048)
   • Auto-Renew (checkbox), Fingerprint (SHA-256), Notes

   Screenshot pending zertifikate-erfassen-02 Empty 'Add Certificate' dialog with Common Name, Issuer, Valid From/To, Status, Key Type

   The empty 'Add Certificate' dialog. Common Name and status are required.

3. Save. Click “Save”. The certificate appears in the list, sorted in by Valid To.

   Screenshot pending zertifikate-erfassen-03 Certificate list after saving, showing the new entry and status indicator

   After saving, the certificate appears in the expiry-sorted list.

API (curl)

The same action via the REST API: a POST to /api/v1/certificates. Only common_name is required; status defaults to active.

Create a certificate

curl -X POST https://demo.notory.io/api/v1/certificates \
  -H "Authorization: Bearer inv_dein_token" \
  -H "Content-Type: application/json" \
  -d '{
    "common_name": "www.example.com",
    "san": ["example.com", "api.example.com"],
    "issuer": "Let'\''s Encrypt R3",
    "valid_from": "2026-05-01T00:00:00Z",
    "valid_to": "2026-07-30T00:00:00Z",
    "key_type": "RSA",
    "key_size": 2048,
    "fingerprint_sha256": "9F:86:D0:81:88:4C:7D:65...",
    "auto_renew": true,
    "status": "active",
    "associated_asset_id": null
  }'

On success, the API responds with HTTP 201 Created:

Response (201 Created, shortened)

{
  "id": "c4e8b2a1-6f37-4d90-8b52-1a7c3e9d0f68",
  "tenant_id": "3d9b0c12-4e5a-4f88-b1c7-2a9e6d4f0011",
  "common_name": "www.example.com",
  "san": ["example.com", "api.example.com"],
  "issuer": "Let's Encrypt R3",
  "valid_from": "2026-05-01T00:00:00Z",
  "valid_to": "2026-07-30T00:00:00Z",
  "key_type": "RSA",
  "key_size": 2048,
  "auto_renew": true,
  "status": "active",
  "associated_asset_id": null,
  "created_at": "2026-07-08T09:30:00Z",
  "updated_at": "2026-07-08T09:30:00Z"
}

Two fields are only available via the API (not in the web form): the SAN list (san, additional covered domains) and the asset link (associated_asset_id, UUID of the associated asset). Valid status values: active, expiring_soon, expired, revoked.

Possible errors: 401 (token missing/invalid), 403 (no write access or the Certificates module is not in your tier), 422 (validation — e.g. empty common_name).

What happens behind the scenes?

• Tenant assignment: The certificate is assigned to your current tenant (tenant_id) and is invisible to other tenants.
• Audit trail: Creator/editor are recorded as created_by/updated_by with a timestamp.
• Sorted by expiry: The list is sorted server-side by Valid To in ascending order — upcoming expirations appear at the top.
• Default values: Without input, status = active and auto_renew = false apply.
• Asset link: If an associated_asset_id is set and the asset is later deleted, the link is automatically cleared (the certificate remains).
• No webhook: Creating a certificate does not trigger a webhook event in the current version.

Related topics

• Certificates — Overview
• Expiry monitoring & notifications
• Renew a certificate
• Manage SSH keys
• API introduction — authentication, base URL, error codes