Connect your account

Before your software can use Knovas, it needs a digital ID (a certificate). This page shows how to get it, keep it safe and renew it.

Two entrances

Knovas has two entrances on the same server address:

Entrance	Used for	Needs your certificate?
`https://api.knovas.ch` (port 443)	Signing up once with your registration key	No
`https://api.knovas.ch:8443`	Everything else: upload, search, delete, renew certificates	Yes

Common mistake

If a /secured/... call returns 404 Not Found, you probably forgot :8443 in the address.

Step 1: Get your registration key

Knovas sets up your account and sends you an email with a registration key. The key already knows your name, email and whether you are an organisation or a person. It works only once.

Step 2: Exchange the key for a certificate

Send the key to /create_entity. Only add the details that are still missing: an organisation sends its address; a person within an organisation sends first and last name (an address is optional). The answer contains your credentials, so save them straight away. Both examples do that for you.

For an organisation

umask 077   # files created below are readable by you only
RESPONSE=$(curl -s -X POST https://api.knovas.ch/create_entity \
  -H "Content-Type: application/json" \
  -d '{
    "key": "<your registration key>",
    "entity_data": {
      "address": "Beispielstrasse 70",
      "postal_code": "8001",
      "city": "Zurich",
      "country": "Switzerland"
    }
  }')

# Remove old copies first: permissions only apply to newly created files
rm -f client_cert.pem client_key.pem ca_root_cert.pem
echo "$RESPONSE" | jq -r '.certificate_pem' > client_cert.pem
echo "$RESPONSE" | jq -r '.private_key'     > client_key.pem
echo "$RESPONSE" | jq -r '.ca_root_cert'    > ca_root_cert.pem

import os
import requests

r = requests.post("https://api.knovas.ch/create_entity", timeout=60, json={
    "key": "<your registration key>",
    "entity_data": {
        "address": "Beispielstrasse 70",
        "postal_code": "8001",
        "city": "Zurich",
        "country": "Switzerland",
    },
})
r.raise_for_status()
answer = r.json()

for field, filename in [("certificate_pem", "client_cert.pem"),
                        ("private_key", "client_key.pem"),
                        ("ca_root_cert", "ca_root_cert.pem")]:
    # Start from a fresh file that only you can read (0o600). Permissions
    # only apply to new files, so an old copy is removed first.
    if os.path.lexists(filename):
        os.remove(filename)
    fd = os.open(filename, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
    with os.fdopen(fd, "w") as f:
        f.write(answer[field])

For a person within an organisation

umask 077   # files created below are readable by you only
RESPONSE=$(curl -s -X POST https://api.knovas.ch/create_entity \
  -H "Content-Type: application/json" \
  -d '{"key": "<your registration key>",
       "entity_data": {"first_name": "Jane", "last_name": "Doe"}}')

# Remove old copies first: permissions only apply to newly created files
rm -f client_cert.pem client_key.pem ca_root_cert.pem
echo "$RESPONSE" | jq -r '.certificate_pem' > client_cert.pem
echo "$RESPONSE" | jq -r '.private_key'     > client_key.pem
echo "$RESPONSE" | jq -r '.ca_root_cert'    > ca_root_cert.pem

import os
import requests

r = requests.post("https://api.knovas.ch/create_entity", timeout=60, json={
    "key": "<your registration key>",
    "entity_data": {"first_name": "Jane", "last_name": "Doe"},
})
r.raise_for_status()
answer = r.json()

for field, filename in [("certificate_pem", "client_cert.pem"),
                        ("private_key", "client_key.pem"),
                        ("ca_root_cert", "ca_root_cert.pem")]:
    # Start from a fresh file that only you can read (0o600). Permissions
    # only apply to new files, so an old copy is removed first.
    if os.path.lexists(filename):
        os.remove(filename)
    fd = os.open(filename, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
    with os.fdopen(fd, "w") as f:
        f.write(answer[field])

Step 3: Keep your files safe

Field in the answer	Saved as	What it is
`certificate_pem`	`client_cert.pem`	Your certificate (your digital ID)
`private_key`	`client_key.pem`	Your secret key. Sent only this once.
`ca_root_cert`	`ca_root_cert.pem`	Knovas’ certificate, to check you really talk to Knovas
`client_id` / `organisation_id`	—	Your account number, for support

Keep your key safe

Store the files in a secrets manager or password vault.
Never commit them to a code repository or send them by email.
Anyone with your key can read and change your documents.

Step 4: Test the connection

Pass the three files with every request. This call shows who Knovas thinks you are and when your certificate expires:

curl --cert client_cert.pem --key client_key.pem --cacert ca_root_cert.pem \
  https://api.knovas.ch:8443/secured/cert-info

import requests

BASE = "https://api.knovas.ch:8443"
AUTH = dict(
    cert=("client_cert.pem", "client_key.pem"),  # your certificate and private key
    verify="ca_root_cert.pem",                   # Knovas' certificate
    timeout=60,
)

r = requests.get(f"{BASE}/secured/cert-info", **AUTH)
r.raise_for_status()
print(r.json()["certificate"])

In Python, AUTH is what makes a request use your certificate: cert= points to your certificate and key, verify= to Knovas’ certificate. The Python examples in these docs always start with these few setup lines.

Step 5 (recommended): Create your own key

Your first key travelled over the internet once. For everyday use it is safer to create a new key on your own computer and ask Knovas to sign it. This new key never leaves your systems.

umask 077              # new files are readable by you only
rm -f my_key.pem       # permissions only apply to newly created files

# 1. Create a new key and a signing request on your computer
openssl req -new -newkey rsa:2048 -nodes \
  -keyout my_key.pem -out my_request.csr -subj "/CN=My Integration"

# 2. Ask Knovas to sign it (uses your current certificate)
curl -X POST https://api.knovas.ch:8443/secured/sign_certificate \
  --cert client_cert.pem --key client_key.pem --cacert ca_root_cert.pem \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile csr my_request.csr '{csr: $csr, validity_days: 365}')" \
  | jq -r '.certificate' > my_cert.pem

import requests

BASE = "https://api.knovas.ch:8443"
AUTH = dict(
    cert=("client_cert.pem", "client_key.pem"),  # your certificate and private key
    verify="ca_root_cert.pem",                   # Knovas' certificate
    timeout=60,
)

# pip install cryptography
import os
from cryptography import x509
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import rsa
from cryptography.x509.oid import NameOID

# 1. Create a new key and a signing request on your computer
new_key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
csr = (x509.CertificateSigningRequestBuilder()
       .subject_name(x509.Name([x509.NameAttribute(NameOID.COMMON_NAME, "My Integration")]))
       .sign(new_key, hashes.SHA256()))
# Start from a fresh key file that only you can read (0o600). Permissions
# only apply to new files, so an old copy is removed first.
if os.path.lexists("my_key.pem"):
    os.remove("my_key.pem")
fd = os.open("my_key.pem", os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
with os.fdopen(fd, "wb") as f:
    f.write(new_key.private_bytes(serialization.Encoding.PEM,
                                  serialization.PrivateFormat.PKCS8,
                                  serialization.NoEncryption()))

# 2. Ask Knovas to sign it (uses your current certificate)
r = requests.post(f"{BASE}/secured/sign_certificate", **AUTH, json={
    "csr": csr.public_bytes(serialization.Encoding.PEM).decode(),
    "validity_days": 365,
})
r.raise_for_status()
with open("my_cert.pem", "w") as f:
    f.write(r.json()["certificate"])

From now on, use my_cert.pem with my_key.pem. The answer contains no private key, because you already have it.

Renewing your certificate

Certificates expire (by default after one year, at most after three). Check the date with /secured/cert-info and repeat Step 5 before it runs out. If your certificate has already expired, contact Knovas for a new registration key.

Questions? Write to contact@knovas.ch.

This page describes Knovas 1.3.0. Last updated 24 September 2026.