Skip to content

API keys & authentication

Every non-interactive call to CertIntel - a reporting script, an agent, a CI job - authenticates with an API key in a single header:

X-Api-Key: cik_<prefix>.<secret>

(Authorization: Bearer cik_<prefix>.<secret> also works, for tooling that only speaks bearer tokens.)

A key's secret is shown exactly once, at creation - CertIntel stores only its hash. If you lose it, rotate the key for a new secret; there is no way to recover the original.

Two kinds of key

Kind Created by Typical holder
Integration key Directly, on the API Keys page A custom script, CI pipeline, or third-party integration
Agent key Exchanging an install token (see Install tokens & enrollment) The CertIntel Windows Agent, one key per device

An agent key is created pending and does nothing until an administrator approves it on the Agents page - see Install tokens & enrollment for what that means and how to review a newly-enrolled device before it starts reporting.

Scopes

A key's scope decides what it can do, independent of which kind it is:

  • write - ingest-only. Can submit renewal events, agent check-ins, and internal-certificate scan reports, and nothing else - it holds no other permission at all, so it cannot even read back the certificates it just submitted. This is the scope every reporting script and agent uses.
  • dashboard - read access to most resources (certificates, organizations, activity, renewals, internal certs) plus day-to-day management: create/edit monitored targets and CT-watched domains, acknowledge certificates, manage DNS delegations, and issue/revoke write-scoped keys. Cannot delete resources, manage users, or mint an admin-scope key.
  • admin - full management within the key's own scope: its bound organization, or the whole tenant if left unconfined - deletes and user management included. An org-confined admin key cannot create an unconfined, tenant-wide admin key; only an already-unconfined admin key (or a real tenant-administrator session) can do that.
  • releases - one action only: publish or replace a component's update manifest. Only a platform administrator can create one.

Narrowing a write key to specific resources

A write-scoped key can be narrowed at creation to a subset of renewals / checkins / internal_certs, so a given script can only ever submit one kind of data even if its secret leaks. Leave it unnarrowed for a script that legitimately needs to post more than one (e.g. the bundled ACME wrapper scripts, which post check-ins and renewal events).

Organization scope

A key is bound to one child organization, or - for an organization administrator creating one from the tenant level - left tenant-wide. A tenant-wide key can act across every organization in the tenant; the request body's organization field then selects which one a given call applies to.

Expiry, rotation, and revocation

  • Keys can optionally be given an expiry when created.
  • Rotate issues a new secret for the same key - the old secret stops working immediately, but the key's identity, history, and any grants tied to it (e.g. Delegated DNS-01 access) are unchanged.
  • Revoke disables the key without deleting it - its reporting history stays in place. A revoked key can be reactivated later.
  • Delete removes the key permanently from the active list; reporting history it produced is preserved, and the device or script returns automatically if it reports again with a still-valid credential of its own (for an agent, a fresh install-token exchange).

Bad requests are opaque, on purpose

A wrong secret, a revoked key, and an expired key all produce the exact same 401 Unauthorized - there's no way to distinguish "this key doesn't exist" from "this key is disabled" from the outside, so a leaked prefix can't be used to probe a key's state. The one deliberate exception is a pending agent key, which returns a distinguishable 428 Precondition Required - see Install tokens & enrollment for why that one case is different.