Planned: read status by API

Read-only order and certificate status, plus webhooks for expiry and status changes. API keys would need a customer sign-in, which Klarseal does not offer. Every status string the API returns would be the same string the order page shows and our emails use — there is one vocabulary, not one per surface.

Specified, not deployed

https://api.klarseal.com is reserved and answers nothing. The API is planned, not available, and no opening date is promised. No key has been issued. Orders are followed through the status link in the emails Klarseal sends. Read this as the contract being built — the field names, status values and event names below are fixed here first so that nothing shifts under you after you integrate.

Three read resources

Orders, certificates and invoices. JSON over HTTPS, a bearer key in theAuthorization header, versioned under /v1/ — a breaking change would take a new prefix, added fields would not.

GET /v1/orders/{order} · planned

curl https://api.klarseal.com/v1/orders/KS-2026-0001 \
  -H "Authorization: Bearer ks_live_..." \
  -H "Accept: application/json"

200 OK · order

{
  "order": "KS-2026-0001",
  "product": "certum-standard-cs-cloud",
  "status": "validation_identity",
  "status_label": "Identity check needed",
  "next_step": "The person named on the order confirms their identity with Certum. Check that inbox.",
  "who_acts": "customer"
}

200 OK · certificate

{
  "certificate": "cert_8f2c41",
  "order": "KS-2026-0001",
  "subject": "Archi Systems AS",
  "status": "active",
  "status_label": "Active until 14.03.2027",
  "issued_at": "2026-03-11",
  "expires_at": "2027-03-14",
  "days_remaining": 187
}

Webhook delivery · certificate.expiring

POST https://your-app.example/hooks/klarseal
X-Klarseal-Signature: sha256=...

{
  "event": "certificate.expiring",
  "sent_at": "2027-02-12T09:00:00Z",
  "order": "KS-2026-0001",
  "certificate": {
    "certificate": "cert_8f2c41",
    "status": "expiring",
    "status_label": "Renew before 14.03.2027",
    "expires_at": "2027-03-14",
    "days_remaining": 30
  }
}

The four fields that matter

status: A stable machine identifier from the shared status vocabulary. Switch on this; never print it.
status_label: The only status string to show a person. Identical to what the order page and our emails say.
next_step: One sentence saying what happens next, in plain language and without blaming anyone.
who_acts: Who is holding the order up right now: customer, klarseal, ca, or none.

Every status you can receive

This is the complete list. status_label is what you show a person;who_acts is the most useful thing a status can say, because it answers “is this waiting on me?” without an email.

status_label	who_acts	next_step
Awaiting payment	You	Your card payment has not completed yet. Nothing has been submitted.
Order received	Klarseal	We are preparing your application before it goes to the certificate authority.
Sent to Certum for validation	Certum	Certum has your application. They contact you directly if they need anything.
Certum is checking your company	Certum	No action from you unless Certum asks for a document.
Identity check needed	You	The person named on the order confirms their identity with Certum. Check that inbox.
Authorisation needed	You	Someone who can sign for the company has to approve this order.
Certificate issued	—	Your certificate is in your SimplySign account. Install the app and sign your first file.
Active until 14.03.2027	—	Nothing to do. We remind you before it expires.
Renew before 14.03.2027	You	Renewing early costs nothing extra and avoids a gap in signing.
Expired	—	Files you signed and timestamped before expiry still verify.
Not issued — see details	Klarseal	We refund the full amount and explain what happened.

Dates render as DD.MM.YYYY everywhere, including in the API’s human-readable labels; machine fields such as expires_at stay ISO 8601. The dot beside a label is the only place colour carries meaning on this site, and the label always states the status in words as well.

Webhooks

order.status_changed: An order moved to a new status. Carries the new label, who acts next, and the previous status.
certificate.issued: Certum issued a certificate against an order. Carries the subject, serial and validity window.
certificate.expiring: Sent at 90, 30 and 7 days before expiry, so a renewal can be started before signing stops.
certificate.expired: The validity window closed. Files signed and timestamped before this still verify.
invoice.issued: An invoice was raised. Carries net, MVA, total and a link to the document and its JSON twin.

Building against this?

Tell us what you would poll for and what would have to reach you as a webhook. The first release is small on purpose, and this is what decides its shape.

Order certificate Read about the planned MCP server

Questions about the API

Certificates are issued by Certum, a certificate authority on the EU Trusted List. Klarseal operates the order and reports its status; Certum decides and issues.

Can I call the API today?

No. https://api.klarseal.com is a reserved host name and answers nothing, and there are no keys to issue because Klarseal does not offer the customer sign-in that would issue them. The API is planned and no opening date is promised. This page is the contract it is being built against — field names, status values and event names are fixed here first, precisely so nothing changes under you later.

Is there a write API? Can I order a certificate over REST?

Not in the first release. The status API is read-only: orders, certificates and invoices, and nothing that changes them. Ordering involves a payment, three acknowledgements at checkout and an authorisation by someone who can sign for the company, none of which belong behind an API key. A REST ordering API is something we want to build, because Certum does not offer one publicly — but it does not exist, and we are not going to imply that it does.

Why do you offer webhooks when the certificate authority does not?

Because someone has to poll. Certum’s partner API is request-response with no callbacks, so status changes can only be discovered by asking repeatedly. Klarseal runs that poller as part of operating the order, and the webhook is simply us telling you what we already found out. That is the whole difference: you get a push, we keep the retry logic.

Will the API tell me when my certificate will be issued?

No, and it never will. It reports the step an order is on and who is acting, and it carries no date or time window. Certum reviews the documents and checks the named person’s identity on its own schedule, so any date or window Klarseal returned would be a guess dressed as a fact. What we commit to is that the application reaches Certum complete.

How will API keys work?

They would be issued from a customer sign-in, which Klarseal does not offer. Keys would be read-only, shown once at creation and stored hashed afterwards. Keys are server-side credentials: never ship one in a browser bundle or a mobile app, because anyone holding it could read your orders and invoices. Rotation would create a second live key so you can move over without downtime, and revoking one would take effect on the next request.