Rotate and revoke credentials

emisar issues several kinds of secret, and they do not behave the same way. This page maps each one — what it can do, how it rotates, what revocation reaches — and links the page that owns each walkthrough.

Which credential is this?#

Start with your row, then follow its owner page. The runner-held credentials live on Runner credentials.

Credential	Prefix	Where it is used and stored	Authority	Routine rotation	Immediate containment	Overlap	Effect on sessions and runners	Owner page
Agent key	`emk-`	A local client or bridge config on a workstation. OAuth clients hold access and refresh tokens instead.	Calls MCP tools with API-client permissions and its owner's current runner and pack scope	Rotate the key — the successor inherits its name and kind	Revoke — cannot be undone, and it takes the rotation chain with it	Yes — until the successor's first authenticated request or the old key expires	No sign-in ends. Revocation also stops OAuth access and refresh tokens backed by that key.	Manage agents & keys
Audit-export token	`emk-export-`	Your SIEM or poller config	Reads GET /api/audit for this account, and nothing else	Mint a second token, move the collector to it, revoke the first	Revoke	Yes, but you create it — two live tokens until you revoke	None — it has no session and reaches no runner	Audit & SIEM
Runner enrollment key	`emkey-enroll-`	The provisioning template that sets EMISAR_ENROLLMENT_KEY, and /etc/emisar/runner.env on the host	Registers new runners into the account	Mint new, update the template, boot one host, revoke old	Revoke — stops new registrations only	Yes — both keys register until you revoke the old one	Connected runners are unaffected. They use their own tokens.	Runner credentials
Per-runner token	`rnrtok-`	Cached on the host by the runner, issued at registration	That one runner's control connection	Automatic at 60 days, or request an earlier rotation on the runner's page	Delete the runner — it cannot be restored. Disable is the reversible lever	Yes — up to 24 hours after the swap, without extending its existing expiry	That runner disconnects. If disabled, the service keeps retrying. If deleted, it exits.	Runner credentials
OIDC client secret	—	The SSO connection here, and the app registration at your IdP	Authenticates emisar to your identity provider during sign-in	Create at the IdP, save here, complete a real sign-in, delete the old	Disable or delete the connection	Your IdP's feature — some hold two secrets at once	Replacing the secret ends no session. Disabling or deleting the connection revokes sessions authenticated through it.	Single sign-on
SCIM bearer	`ems-`	Your IdP's provisioning connector	Directory reads and writes on that connection	Rotate token — it takes effect immediately	Rotate token, or disable directory sync	None — provisioning fails until the IdP holds the new value	No session ends. Provisioning stops until the connector is updated.	Directory sync
Signed-dispatch leaf	—	The operator's machine, in the MCP bridge process, as the signing key and its certificate	Signs an action a runner that trusts the CA will accept	Mint a new certificate under the CA the fleet already trusts	None per leaf — rotate the CA across the fleet	Yes — every unexpired certificate under a trusted CA keeps working	No runner is touched and no run is dropped	Signed dispatch
Signed-dispatch CA	—	The trusted_cas list on every runner. The CA private key stays offline.	Vouches for every leaf a runner will accept	Add the new CA, reissue leaves, remove the old, reload every runner	The same rotation, run urgently	Yes — while both CAs are in the list	Each step applies on reload without dropping a run. A missed host still trusts the old CA.	Signed dispatch
Pack or provider credential	—	/etc/emisar/runner.env on the host, read at process start	Whatever the provider grants that value. The control plane does not distribute or store it as configuration.	Rotate at the provider, update runner.env, restart the service	Revoke at the provider	The provider's own, if it issues overlapping credentials	The restart interrupts actions in flight on that host. Nothing else changes.	Runner credentials

The rotation sequence#

Each credential below follows the same seven steps. If a credential has no overlap window, its section shows which interruption to expect.

Inventory: find every consumer that holds the current value.
Create the successor.
Update the consumer.
Verify the new path with a real call, sign-in, or registration.
Revoke the predecessor.
Verify the old value now fails.
Read the audit trail: the mint, the revoke, and who did each.

Never paste a secret into anything that stores it.

Not a support ticket, a run reason, an action argument, or a copied shell example. A secret is shown once at creation — if the consumer misses it, mint another instead of saving the value anywhere.

Agent keys#

Rotation and revocation live on the agent's row on Agents. Rotate uses automatic setup when the agent supports it; otherwise it shows a new key to copy into the agent's settings. The old key is retired only when the replacement makes its first call, unless it expires sooner. Revocation cannot be undone. The reach of each — the rotation chain, OAuth-backed connections, scope, and expiry — is in Manage agents & keys.

Audit-export tokens#

To rotate, create a new token in SIEM export using Create export token, and revoke the old one after the rotation completes. The cursor is not tied to the token, so your SIEM keeps streaming through a rotation. The cutover walkthrough — with cursors, paging, and rate limits — is in Audit & SIEM.

OIDC client secrets and SCIM bearers#

Both live on the same SSO connection.

— OIDC client secret. The secret is issued at your IdP, and whether two can be live at once is your IdP's feature — check there before a swap. In emisar the field is write-only — a blank save keeps the existing value — and a connection test checks only discovery and reachability — so sign in at least once after rotating to confirm the new secret works. Replacing the secret does not sign out anyone.
— SCIM bearer. Rotate token replaces the bearer immediately with no overlap: the old value stops authenticating right away, and the IdP connector fails until it has the new one. Existing signed-in users stay online.

Disabling or deleting a connection signs out everyone who signed in through it and blocks new sign-ins. It does not touch API keys or OAuth credentials, and it does not suspend or delete members. Disabling SCIM also makes roles and runner access editable in the console again and discards the last group snapshot.

The provider-side steps are in Single sign-on and Directory sync. Authentication covers complete offboarding.

Signed-dispatch keys#

You create and hold signing keys yourself — the portal never receives or stores them. Rotating one does not touch any runner: mint a new key and certificate under the CA your fleet already trusts, and point the MCP client at the new key. Give the certificate a lifetime longer than the freshness window plus the time an approval usually takes, so the original signature is still valid when an approved run dispatches.

There is no per-certificate revocation list.

emisar publishes no revocation list for signing certificates — a leaked leaf key works until its certificate expires, and short lifetimes limit exposure. For earlier containment, rotate the trust root: add the new CA beside the old, reissue operator certificates, then remove the old CA and reload every runner — the control plane cannot do that reload for you.

The CA model, certificate scopes, and the reload mechanics are in Signed dispatch.

← Previous

Security incidents

Policies & approvals