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-factor sign-in does not apply to API keys: a key never asks for a code, even in a workspace that requires two-factor sign-in for its users. Protect keys accordingly.

Two kinds of key¶

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 - reporting access for renewal events, check-ins, and internal certificate scans. It does not grant general inventory reads or management. The Agent also uses specifically authorized identity/policy and assignment endpoints needed to collect those reports. This is the scope used by reporting scripts and Agent credentials.
• 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 approve newly enrolled agents. Cannot delete resources, manage users, or mint any API 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. The same bar applies on the platform console's key page, where every new key is unconfined: a tenant administrator of the platform tenant can mint or rotate write / dashboard keys, and only a platform administrator can mint, rotate, edit, or revoke an unconfined admin or releases key, because such a key carries platform-administrator authority.

A releases scope also exists for CertIntel's own release-publishing tooling. Only a platform administrator can create it; it is not used by customers.

Who can manage keys¶

Among the built-in roles only Administrator (and tenant administrators) creates, rotates, revokes, re-enables or deletes API keys and agent credentials; Operator no longer does. A custom role may hold api_keys.create, update, delete or admin, but a key never carries more than its creator holds: the scope's permission set must be a subset of what you hold in the key's organization, or the request answers 403 naming what is missing. Rotating and re-enabling are checked the same way, because whoever learns the new secret inherits the key's authority. Approving a freshly enrolled agent is the separate agents.create permission (Operator and Administrator have it), and re-registering one is agents.update. See Delegation is bounded.

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).

Allowing a key to request Private CA certificates¶

Requesting certificates from a CertIntel Private CA is a separate, opt-in switch on a key, not a write resource: enrolling an Agent never lets it mint certificates by itself. A user holding private_ca.update in the key's organization turns it on from the Agents page (Allow private CA / Forbid private CA), from the CA page under Who may request certificates, or with POST /api/v1/api-keys/{key_id}/private-ca-issuance and {"enabled": true}.

Only an organization-confined write key (an Agent or an integration key) can be allowed; the switch is refused for admin, dashboard and workspace-wide keys (Only an organization-confined write key (an agent) can be allowed to request certificates.), and a revoked key must be reactivated first. An allowed key can list the organization's active CAs and submit CSRs, and nothing else: it cannot see issued certificates, revoke, export keys or configure a CA. Each switch is recorded in the activity log.

Organization scope¶

A key is bound to one child organization, or left Workspace-wide (all organizations) by a caller with workspace-wide authority. The organization selected in the top bar is pre-selected in the form. Creating a credential cannot broaden the issuer's scope: an organization-confined caller cannot mint a workspace-wide key (Only a tenant administrator can create a tenant-wide key.). Check the Organization selection before creating it.

An organization-bound key reports to that organization. A tenant-wide reporting key resolves to the tenant's default organization, or its only organization; if neither is unambiguous, reporting returns a conflict instead of guessing. The GET /api/v1/auth/me response exposes reporting_organization_id. Do not assume an ingest payload can redirect an organization-bound key's reports elsewhere.

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. Rotating an agent key also clears its unregistered flag.
• 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: it can no longer authenticate and cannot be reactivated (Deleted keys cannot be reactivated. Create a new key.). Reporting history it produced is preserved. A deleted agent must enrol again with a fresh install-token exchange.

The Last used column updates for every authenticated request, including reads, at most once a minute.

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.

Browser sessions cannot be used from another website: the API does not allow credentialed cross-origin requests, so a browser-based integration on a different origin must use an API key.