List an agent's certifications
Lists the AgentCertificationV1 credentials attached to the agent for builtin.agent_certification, newest first, with each one's validation status, operating-profile check and configuration standing. The standing is worked out on each read, from each of the agent's active keys' newest request: a key is certified when its state gave the configuration the certification names, cordoned when it gave another (the gateway refuses its requests wherever the certification is required), unknown when no configuration could be derived from it, and idle after 7 days without a request; the certification is current when every key that made a request lately is certified, partly_drifted when some are, drifted when none are, and idle when no key made a request lately. Each key also says how it joined the agent; who added it goes only to an admin and the agent's operators. An agent holds one current certification per program version, configuration and operating profile, so certifications of configurations it no longer runs, or doesn't run yet, stay current beside the one it runs; a row superseded by a newer certification of the same program version, configuration and profile is kept with current=false. Revocation status and the operating-profile check are as the background refresh last left them; the validity window is re-read against the time of the request, for validation_status, the total and each item alike. An agent whose ID is not a urn:uuid holds none. Readable by an admin and by users bound to the agent, as operator or viewer. An API key reads as its holder when it has full access, or when it is scoped to view_agent_certifications and bound to no project, so deploy automation can pull an agent's certifications; the holder's binding still decides which agents it sees.
https://<host>/api/v1/agents/{agentId}/certificationscurl --request GET \
--url 'https://<host>/api/v1/agents/{agentId}/certifications' \
--header 'Authorization: Bearer <token>'const response = await fetch("https://<host>/api/v1/agents/{agentId}/certifications", {
method: "GET",
headers: {
"Authorization": "Bearer <token>"
}
});
const data = await response.json();interface AgentCertificationListResponse {
correlation_id?: string;
items?: Record<string, unknown>[];
total_count?: number;
}
const response = await fetch("https://<host>/api/v1/agents/{agentId}/certifications", {
method: "GET",
headers: {
"Authorization": "Bearer <token>"
}
});
if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);
const data: AgentCertificationListResponse = await response.json();import requests
response = requests.get(
"https://<host>/api/v1/agents/{agentId}/certifications",
headers={
"Authorization": "Bearer <token>",
},
)
response.raise_for_status()
print(response.json())package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, err := http.NewRequest(http.MethodGet, "https://<host>/api/v1/agents/{agentId}/certifications", nil)
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "Bearer <token>")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
data, err := io.ReadAll(res.Body)
if err != nil {
panic(err)
}
fmt.Println(res.Status, string(data))
}import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Example {
public static void main(String[] args) throws Exception {
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://<host>/api/v1/agents/{agentId}/certifications"))
.header("Authorization", "Bearer <token>")
.method("GET", HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode() + " " + response.body());
}
}using System.Net.Http.Headers;
using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Get, "https://<host>/api/v1/agents/{agentId}/certifications");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", "<token>");
using var response = await client.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");<?php
$ch = curl_init('https://<host>/api/v1/agents/{agentId}/certifications');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer <token>',
],
CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
echo $status . " " . $response . PHP_EOL;require "net/http"
uri = URI("https://<host>/api/v1/agents/{agentId}/certifications")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer <token>"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
http.request(request)
end
puts "#{response.code} #{response.body}"// Cargo.toml dependencies: reqwest, tokio (features "full")
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let response = reqwest::Client::new()
.get("https://<host>/api/v1/agents/{agentId}/certifications")
.header("Authorization", "Bearer <token>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Ok(())
}Authorizations
BearerAuth· API key in header "Authorization" — Type "Bearer" followed by a space and a sign-in token: a Guardian Platform JWT, or an OIDC ID token in a standalone deployment.ApiKeyAuth· API key in header "Authorization" — Type "Bearer" followed by a space and a Guardian Platform API key. Project-scoped routes and registration tokens check the key's scopes and project binding. Per-agent routes accept a key bound to no project that has empty scopes or full access, which acts as its holder, or a scope for what the route does: submit_agent_assessments reads an agent (its detail, configurations, state history and the files a state references, definitions, tools and operating profile, as its assessments rest on), view_agent_certifications reads its certifications, and manage_programs or review_agent_assessments attach a certification. A state's raw snapshot and findings, its audit exchanges and plugin events, and saving its operating profile take full access. A scope counts only while the key's holder still holds that permission in the key's organization, which auth-service reports as keyHeldScopes. A key never acts as an admin, so its holder's binding to the agent still decides.
Parameters
Path parameters
| Name | Type | Description |
|---|---|---|
agentIdrequired | string | Agent ID |
Query parameters
| Name | Type | Description |
|---|---|---|
current_only | boolean | Only certifications the gateway enforces from |
validation_status | string | valid, expired, not_yet_valid, revoked, invalid or untrusted_issuer |
limit | integer | Page size (default 50, max 200) |
offset | integer | Page offset |
Responses
200OK
correlation_idstringitemsinternal_controlhttp.agentCertificationView[]Show properties
Array of
internal_controlhttp.agentCertificationViewagent_idstringauthorized_by_didstringconfiguration_cidstringconfiguration_standingobjectConfigurationStanding is how the agent's keys stand against what a certification the gateway can honor names: absent for one that is revoked, expired, not yet valid, invalid or untrusted, which no key stands against
Show properties
keysagentcertification.KeyStanding[]Show properties
Array of
agentcertification.KeyStandingadded_bystringWho added it; told only to an admin and the agent's operators
added_by_api_key_idstringThe API key's public ID; told only to an admin and the agent's operators
added_by_emailstringTheir email; told only to an admin and the agent's operators
added_viastring (enum)AddedVia is how the key joined the agent (registration_token, api_key or control_plane), AddedBy and AddedByEmail who added it, and AddedByAPIKeyID the API key's public ID.
One of
registration_tokenapi_keycontrol_planeconfiguration_cidstringConfigurationCID is what its newest request's state gave, as a urn:cid; ConfigurationError why it gave none.
configuration_errorstringdidstringlast_seen_atstringstateobjectOne of
certifiedcordonedunknownidleShow properties
object (enum)· one of certified, cordoned, unknown, idle
statusobjectOne of
currentpartly_drifteddriftedidleShow properties
object (enum)· one of current, partly_drifted, drifted, idle
credential_idstringcredential_statusagentcertification.CredentialStatusMetadata[]Show properties
Array of
agentcertification.CredentialStatusMetadataidstringrawobjectShow properties
Map of
anystatus_list_credentialstringstatus_list_indexstringstatus_purposestringtypestring
credential_status_checked_atstringcurrentbooleanissuer_didstringobserved_atstringoperating_profile_checkagentcertification.OperatingProfileCheckShow agentcertification.OperatingProfileCheck
attempted_atstringAttemptedAt is the latest check, decided or not, and ErrorCode why it could not decide; empty when it did.
checked_atstringCheckedAt is when Status was last decided. A check that cannot tell leaves it, and Status, as they were.
current_operating_profile_cidstringCurrentOperatingProfileCID is the profile the agent held when Status was last decided, as a urn:cid; empty when it had none.
error_codestringstatusagentcertification.OperatingProfileStatusOne of
matchmismatchunknown
operating_profile_cidstringprogram_cidstringsource_refsagentcertification.SourceRefsShow agentcertification.SourceRefs
credential_idstringsource_cidstring
status_resolutionagentcertification.StatusResolutionShow agentcertification.StatusResolution
checked_atstringmetadataobjectShow properties
Map of
anyrevokedboolean
valid_fromstringvalid_untilstringvalidation_errorsagentcertification.ValidationError[]Show properties
Array of
agentcertification.ValidationErrorcodestringfieldstringmessagestring
validation_statusagentcertification.ValidationStatusOne of
validexpirednot_yet_validrevokedinvaliduntrusted_issuer
total_countinteger
{
"correlation_id": "string",
"items": [
{
"agent_id": "string",
"authorized_by_did": "string",
"configuration_cid": "string",
"configuration_standing": {
"keys": [
{
"added_by": "string",
"added_by_api_key_id": "string",
"added_by_email": "string",
"added_via": "registration_token",
"configuration_cid": "string",
"configuration_error": "string",
"did": "string",
"last_seen_at": "string",
"state": "certified"
}
],
"status": "current"
},
"credential_id": "string",
"credential_status": [
{
"id": "string",
"raw": {
"key": null
},
"status_list_credential": "string",
"status_list_index": "string",
"status_purpose": "string",
"type": "string"
}
],
"credential_status_checked_at": "string",
"current": true,
"issuer_did": "string",
"observed_at": "string",
"operating_profile_check": {
"attempted_at": "string",
"checked_at": "string",
"current_operating_profile_cid": "string",
"error_code": "string",
"status": "match"
},
"operating_profile_cid": "string",
"program_cid": "string",
"source_refs": {
"credential_id": "string",
"source_cid": "string"
},
"status_resolution": {
"checked_at": "string",
"metadata": {
"key": null
},
"revoked": true
},
"valid_from": "string",
"valid_until": "string",
"validation_errors": [
{
"code": "string",
"field": "string",
"message": "string"
}
],
"validation_status": "valid"
}
],
"total_count": 0
}400Bad Request
codestringcorrelation_idstringmessagestring
{
"code": "string",
"correlation_id": "string",
"message": "string"
}401Unauthorized
codestringcorrelation_idstringmessagestring
{
"code": "string",
"correlation_id": "string",
"message": "string"
}403An API key bound to a project, or narrowed by scopes that leave out view_agent_certifications
codestringcorrelation_idstringmessagestring
{
"code": "string",
"correlation_id": "string",
"message": "string"
}404agent_not_found
codestringcorrelation_idstringmessagestring
{
"code": "string",
"correlation_id": "string",
"message": "string"
}500Internal Server Error
codestringcorrelation_idstringmessagestring
{
"code": "string",
"correlation_id": "string",
"message": "string"
}503The certification store is not configured
codestringcorrelation_idstringmessagestring
{
"code": "string",
"correlation_id": "string",
"message": "string"
}