Agent Certifications

About agent certifications

An agent certification attests that one agent, running one configuration, met every control of one Governance Program version. It is issued when a reviewer’s verdict passes an assessment, signed with the platform key, and attached to the Agent Gateway, which can then admit or refuse the agent’s requests by it.

Like a project credential, a certification is a W3C Verifiable Credential: signed, machine-readable, and revocable. Unlike a credential, it belongs to an agent, not to a project.

Key concepts and actions associated with certifications include:

• What a certification covers
• Viewing certifications
• Downloading and retrieving a certification
• Revoking a certification
• Attaching a certification to the gateway
• Enforcing certification at the Agent Gateway

What a certification covers

A certification names exactly:

• The agent, by its ID in the agent registry. The agent’s signing keys can be added, rotated and revoked without affecting it.
• The configuration the assessment pinned, by its configuration CID.
• The operating profile the assessment pinned, by its CID, when one was pinned.
• The program version, by its Manifest CID.
• Who authorized it: the reviewer whose verdict passed the assessment, or the Organization Owner or reviewer who issued it afterward.
• Its evidence: the signed submission, the declarations it froze, and each control’s passing review.
• Its term: it starts an hour before the certification is issued, to allow for clock skew, but never before the last passing review, and ends one certification lifetime after that review, or never when the program version sets no lifetime.

It never covers a project. Certifying an agent changes nothing about the projects it works in or their credentials, and a project credential says nothing about an agent’s certification.

It never covers a later configuration. When anything the agent’s configuration captures changes, in the program’s scope or not, it runs a new configuration, with a new CID, that the certification doesn’t name. Nor does it carry over to a newer program version or another operating profile. To cover a change, assess the agent again and pin the new configuration. An agent can hold certifications of several configurations at once, for example while a change rolls out to some of its instances.

Viewing certifications

An agent’s certifications are listed on its Certification page: select Agents in the sidebar, the agent, then Certification in the agent’s sidebar. The Certifications page, under Agents in the sidebar, lists those of every assessment you can read, each with its status: Active, Expiring Soon, Expired or Revoked. Filter it by Program or Status. Select a certification to open its details: its status and gateway standing, what was certified, who certified it with each statement it rests on, its timeline, and the raw credential.

The agent’s Certification page has three columns that read separately: the certification itself, the gateway’s copy of it, and the agent’s keys against it.

Certificate is the certification’s own status:

• Active: within its term and not revoked
• Expired: its term has ended
• Revoked: revoked before it ended

Gateway is whether the gateway honors it:

Hover a badge to read the reason behind it.

Configuration is the configuration standing: how the agent’s keys stand against the configuration the certification names. Each instance of an agent signs with its own key, and the Control Plane judges each key by its newest request:

The certification’s details list each key with its own state:

• Certified: its newest request ran the configuration this certifies
• Cordoned: its newest request ran another configuration. Wherever a certification is required, the gateway refuses its requests unless another certification names that configuration.
• Unknown: no configuration could be derived from its newest request, so it is refused wherever a certification is required
• Idle: no request in the last 7 days, so it doesn’t count toward the standing

Downloading and retrieving a certification

To download a certification as a signed JSON file:

1. On the agent’s Certification page, select the actions menu (⋮) on the certification’s row
2. Select Download Credential

The file is saved as certification-<credential ID>.vc.json. The certification’s details also show its Credential ID, its Source in the Integrity Service, and the Raw Credential.

To read certifications from your own tools, the Governance Service lists an organization’s certifications, optionally for one agent, and each assessment’s; the Control Plane lists an agent’s certifications as the gateway holds them, with their configuration standing. An API key scoped to View Agent Certifications, with no project binding, reads one agent’s certifications at a time, naming the agent, for agents its holder operates or views. See the Governance Service API reference and the Control Plane API reference for the requests.

Revoking a certification

Revoking a certification invalidates it before its term ends, for example when the agent’s evidence no longer holds. Revocation is final: certifying the agent again takes a new submission.

An Organization Owner can revoke any certification, and the reviewer who authorized one can revoke it while they still review the program.

To revoke a certification:

1. On the agent’s Certification page, select the actions menu (⋮) on the certification’s row, or open the certification
2. Select Revoke Certification
3. Enter the Reason for revoking
4. Select Revoke Certification to confirm

The gateway stops honoring a revoked certification at once. If the gateway couldn’t be updated, Guardian says so, and the gateway may keep honoring it until its next status refresh, within a few minutes. Revoking one agent’s certification affects no other agent and no project credential.

Attaching a certification to the gateway

A certification is attached to the gateway as it is issued, so the gateway can enforce it straight away. If attaching failed, or a renewal isn’t on the gateway yet, Guardian shows the certification as Not on Gateway or warns that a newer certification isn’t on the gateway, and the gateway keeps enforcing the older one until it ends or is revoked.

To attach it, select Attach to Gateway in the warning or in the certification’s actions menu. An Organization Owner, an operator of the agent, or the reviewer who authorized the certification can attach it. The Control Plane verifies the signature, that the certification names this agent, and that any operating profile it names is one of the agent’s profile versions.

Enforcing certification at the Agent Gateway

The gateway enforces certifications through the Agent Certification plugin, builtin.agent_certification, which runs before each request goes to the model provider. A platform admin registers the plugin once (see Register a built-in plugin), and you add it to a configuration with the guardian-plugin CLI, described in Policy as Code.

An entry needs:

• trusted_issuers: the DID the platform signs certifications with. Open a certification’s details and copy its Issuer under Who Certified It.
• required_program_cids: the Manifest CID of each program version agents must be certified under, from the program’s page. Without it, a certification under any program admits the agent. With several, program_match says whether one or all must be covered.
• The request.body.read and agent.badge.write grants, so the plugin can read the tools a request offers and mark the agent’s keys.

Roll it out observe-first, scoped to the project whose agents must be certified:

[configuration]
scope = "project"
project = "Customer Support Agents"

[[deployment.entries]]
plugin_id = "builtin.agent_certification"
hook = "proxy.pre"
order_index = 0
plugin_version = "v1.0.0"
mode = "observability"   # change to "enforcement" after review
timeout_ms = 2000

[deployment.entries.granted_capabilities."request.body.read"]
max_bytes = 33554432

[deployment.entries.granted_capabilities."agent.badge.write"]
allowed_keys = ["operating_profile", "configuration"]

[deployment.entries.config]
trusted_issuers = ["did:key:zPlatformSigningKey"]
required_program_cids = ["urn:cid:bagaProgramManifest"]

In observe mode, the gateway records each decision in the Audit Trail without refusing anything. Review what it would have refused, certify the agents that need it, then switch the entry to mode = "enforcement".

An entry in the global configuration runs on every request through the gateway: it requires a certification of every agent in the organization, and refuses any request without a verified agent even with certification_required = false. On a shared environment, put the entry in the configuration of the projects that require certification, or narrow it with match_rules, rather than in the global floor. A project’s configuration applies only once project context is turned on for the gateway; see Global and project configurations. Every setting is described under Agent Certification in the plugin settings.

Why a request is refused

In enforce mode a refused request gets an error naming the reason, and the Audit Trail records it. The common reasons:

The plugin settings list every reason.

Per-key drift and the cordon

The gateway judges each request by the configuration that request’s own state gives, so drift is caught per instance and per request, with nothing to refresh. When one instance of an agent changes its configuration, such as adding a permission, its very next request is refused with agent_certification_configuration_mismatch. The agent’s other instances keep working.

That key is cordoned: wherever an entry requires a certification, each of its requests is refused while it runs the changed configuration, and its state shows Cordoned. When the entry’s agent.badge.write grant allows the configuration badge, the agent also shows a failing Configuration not certified check. The cordon clears itself: once the instance runs the certified configuration again, or another certification names what it runs, its next admitted request lifts it, with nothing for an administrator to reset. A change that leaves the configuration as it was, such as a new session or user prompt, changes nothing.

Operating-profile enforcement

When a certification names an operating profile, the gateway holds the agent to it. A request that offers a tool or MCP server, or reaches a host, that the profile excludes is refused with agent_certification_profile_excluded, and the agent shows a failing Operating profile breach check until a model request that offers tools, none of them excluded, is admitted. A request the gateway can’t check against the certified profile is refused too, such as one that reaches a host by an address the profile has no rule for. Tools the profile doesn’t declare are never refused; the agent’s Operating Profile page reports them.

The profile is the agent’s, so changing it changes it for every instance: once the Control Plane’s next check finds the change, every request is refused with agent_certification_configuration_mismatch until the agent holds the certified profile again. Certify a configuration that doesn’t offer what the profile excludes, for example by denying an excluded tool in the agent’s settings before pinning. See Agent Certification for how each kind of request is checked.

Related

• Agent Assessments — earn a certification, or renew one for a new configuration
• Governance Programs — the program versions certifications are issued under
• Gateway Policies — every Agent Certification plugin setting and refusal reason
• Policy as Code — apply a plugin configuration with the guardian-plugin CLI
• Audit Trail — see what the plugin decided for each request
• Chart Values — what an operator sets to turn agent certification on