Platform credentials¶
A platform credential is an appliance login - a username and password, or an API token - that you store once in CertIntel and name in a dashboard assignment of an appliance template (F5 BIG-IP, FortiGate, PAN-OS, NetScaler ADC, SonicWall). The Agent fetches it when that workflow deploys a renewed certificate, sealed to a key only that Agent holds, and uses it for one deployment step. It needs Agent 1.5.0 or later and a platform build that offers the feature.
The alternative is a local credential, which never leaves the device: a
local administrator sets it on the Agent with
certintel secret set remote WORKFLOW-ID:credential. A workflow created on the
device always uses a local credential; only a workflow that a dashboard
assignment created can use a platform credential.
The Platform Credentials page¶
Open Settings → Platform Credentials (/platform-credentials).
Add a platform credential takes:
| Field | Meaning |
|---|---|
| Organization | The organization whose Agents may receive it. |
| Name | Up to 120 characters, one line, unique in the organization (The organization already has a credential with that name.), for example FortiGate fw01 API token. |
| Kind | Username and password or API token. Must match the template's credential field: F5 BIG-IP, NetScaler ADC and SonicWall log in with a username and password, FortiGate and PAN-OS with an API token. |
| Description (optional) | Up to 500 characters, one line. |
| Username / Password | For a username and password: up to 256 and 1024 characters. The username cannot contain a colon (The username cannot contain a colon (:).), and no secret field may contain a line break, because the Agent refuses such a credential. |
| API token | For an API token: up to 4096 characters. |
Add credential saves it. An organization can hold at most 200 platform
credentials. The table lists each credential's Organization, Credential
(its name, with the reference platform:<id> below it), Kind, the number of
Assignments that name it, Last delivered, Secret replaced and
Created.
Secrets are write-only
Secrets are write-only: they are never shown again, not even to administrators. Replacing a secret takes effect at the next run. Every delivery and refusal is in the Activity Log. The tenant export leaves them out, and no API response, log or activity entry contains them.
Edit changes the Name and Description, and replaces the secret with New username / New password or New API token. Leave the secret fields empty to keep the stored secret. A replaced secret is used from the next remote run on.
Delete asks Delete the platform credential <name>? <n> assignment(s) name it; their remote runs fail until they name another credential. Deleted credentials are never delivered again.
Permissions¶
| Permission | Lets you | Built-in roles |
|---|---|---|
platform_credentials.read |
See the page and the credentials' names and metadata; name a credential in an assignment (in that organization) | Operator, Auditor, Administrator |
platform_credentials.create |
Add credentials | Administrator |
platform_credentials.update |
Rename credentials, replace their secret, and approve an Agent's sealing key | Administrator |
platform_credentials.delete |
Remove credentials | Administrator |
Tenant administrators hold all four. Custom roles can grant Platform
credentials action by action (see
permissions). Without read in the
Agent's organization, an assignment that names a platform credential is refused
(Your role cannot use the organization's platform credentials.).
Using one in an assignment¶
When you assign an appliance template, its
credential field offers Local secret on the device and Platform
credential: <name> for each credential of the matching kind in the Agent's
organization. The assignment stores only the reference (local or
platform:<id>), never the secret. The card shows <name> (platform
credential).
If the Agent does not take platform credentials, the field says This agent does not take platform credentials: set it on the device with certintel secret set remote <workflow-id>:<field>. With Local, the run fails with credential not set: certintel secret set remote <workflow-id>:<field> until a local administrator sets the value.
When the Agent receives it¶
CertIntel delivers a platform credential only when all of these hold:
- The Agent reports platform credential support (Agent 1.5.0 and later) and its local opt-in is on. A local administrator turns it on on the device (see remote deployment); CertIntel cannot turn it on. The host detail page shows it.
- The Agent's configuration lock is off. A locked Agent never asks for one.
- The workflow was created by an assignment, and that assignment - of the same Agent key - is applying or applied and names this credential.
- The Agent asks with its approved sealing key (below).
Each delivery is sealed (HPKE, X25519) to the Agent's sealing key and bound to the organization, assignment, credential and delivery, and it is valid for 5 minutes. The Agent opens it in memory for one deployment step, never writes it to disk, logs, reports or its state, and clears it from its own buffers afterwards. An Agent can ask for at most 30 deliveries a minute.
Sealing keys¶
The Agent creates its sealing key when its local opt-in is turned on and reports it to CertIntel. No key is used before an administrator approves it - the first key an Agent reports included. Open the Agent's host detail page (Agents → Details) to see the Platform credentials section:
- Local opt-in, as the agent reports it: accepts platform credentials or
off (set only on the device; reported …). This is what the holder of
the Agent's API key reported, not something CertIntel can check; the
device's own setting is in
certintel status --json, underremote_credentials(accepted). - Before the first approval: Sealing key waiting for approval with the key
id and (first reported …), and its Fingerprint (SHA-256 of the
public key): 64 hex digits, of which the key id is the first 16. Platform
credentials are delivered to this agent only after an administrator approves
the key it reported. Approve it if you turned on platform credentials on this
device and its key id matches the device's (certintel status --json, under
remote_credentials): anyone holding this agent's API key could report a key
of their own. Approve key …, which names the key id
(
platform_credentials.update), approves it. Until then, a different key the Agent reports takes its place, and deliveries are refused withsealing-key-unapproved. - Once approved: Sealing key …, pinned … (first reported …).
On the device, certintel status --json shows the key under
remote_credentials → sealing_key (key_id, public_key, created_at);
compare its key_id with the one on the page before you approve.
Only the key the page showed is approved: Approve key sends its key id and fingerprint with the approval. If the Agent reported another key after the page was loaded, nothing is approved and the page shows the key that waits now: The sealing key waiting for approval is now …, not …: the agent reported another key after the one you checked. Nothing was approved. Compare the key now waiting with the one on the device (certintel status --json, remote_credentials.sealing_key) before you approve it.
A key that was pinned when it was first reported, before approval was required, stays pinned.
When the Agent reports a different key - it re-enrolled, or a local
administrator rotated the key with certintel secret rotate-sealing-key - the
section shows New sealing key waiting for approval with the new key id,
(first reported …) and its fingerprint: The agent reported a different
key (it re-enrolled, or a local administrator rotated the key). Platform
credentials are not delivered until it is approved. Approve only if you expect
the change and its key id matches the device's (certintel status --json, under
remote_credentials): anyone holding this agent's API key could report a key of
their own. Approve new key … (platform_credentials.update) approves
it, under the same rule: only the key shown. Deliveries then use the
new key, and first reported becomes the time the new key was first reported.
Approve only keys you expect
Approve a sealing key - the first one or a change - only when you turned on platform credentials on that device or rotated its key yourself. Approving an unexpected key could send credentials to whoever holds that Agent's API key. Someone who has both the Agent's API key and its protected secret store can also open deliveries, so treat both as secrets.
Refusals¶
| Answer | Meaning |
|---|---|
403 remote-credentials-off |
This agent does not accept platform credentials: it does not report platform-credentials, or its local remote_credentials opt-in is off. |
409 sealing-key-unapproved |
This agent's sealing key is not approved: an administrator approves it on the agent's page first. |
409 sealing-key-mismatch |
The request names a sealing key other than the pinned one., or The pinned sealing key of this agent does not match its key id, so nothing was sealed. The agent's next report of its key waits for approval on the agent's page. (CertIntel derives the key id again from the pinned key before every delivery.) |
404 |
The key is unregistered, the credential is unknown or deleted, or no applying or applied assignment of this Agent names it. |
429 |
Too many credential deliveries for this agent; try again in a minute. |
The Agent records each fetch and refusal in its own activity log
(remote-credential-fetched, remote-credential-refused), and the deployment
step fails with the reason.
Activity Log¶
| Action | Message |
|---|---|
platform_credential.create, .update, .delete |
A platform credential was created, updated or deleted. |
platform_credential.rotate |
<user> replaced the secret of the platform credential <name>. |
platform_credential.delivered |
The platform credential <name> was sealed to the agent <agent> for assignment <id> and delivered. |
platform_credential.delivery_refused |
A delivery of the platform credential <name> to the agent <agent> was refused (<reason>). |
agent.sealing_key_reported |
The agent <agent> reported its sealing key <key id>; platform credentials are delivered once an administrator approves it. (with in place of <key id> when it replaces a first key nobody approved yet) |
agent.sealing_key_pinned |
The agent <agent> reported its sealing key <key id>; it is pinned for platform credentials. (earlier entries, from before the first key needed approval) |
agent.sealing_key_changed |
The agent <agent> reported a different sealing key <key id>; platform credentials wait until it is approved. |
agent.sealing_key_approved |
<user> approved the sealing key <key id> of the agent <agent>. (the first key) or <user> approved the new sealing key <key id> of the agent <agent>. |
API¶
| Route | Permission |
|---|---|
GET /api/v1/platform-credentials, GET /api/v1/platform-credentials/{id} |
platform_credentials.read - metadata only, never a secret |
POST /api/v1/platform-credentials (organization, name, kind, description, username, password or token) → 201 |
platform_credentials.create |
PATCH /api/v1/platform-credentials/{id} (a new secret sets rotated_at) |
platform_credentials.update |
DELETE /api/v1/platform-credentials/{id} → 204 |
platform_credentials.delete |
POST /api/v1/agents/{api_key_id}/sealing-key/approve with {"key_id": "<16 hex>", "fingerprint": "<SHA-256, optional>"} → 204. The body names the key you checked: 422 without key_id; 409 sealing-key-changed (with pending_key_id, the key waiting now) when another key waits, and nothing is approved; 409 when no key waits. |
platform_credentials.update |