EQTY LabDocs

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.

gethttps://<host>/api/v1/agents/{agentId}/certifications
bash
curl --request GET \
  --url 'https://<host>/api/v1/agents/{agentId}/certifications' \
  --header 'Authorization: Bearer <token>'
javascript
const response = await fetch("https://<host>/api/v1/agents/{agentId}/certifications", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <token>"
  }
});

const data = await response.json();
typescript
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();
python
import requests

response = requests.get(
    "https://<host>/api/v1/agents/{agentId}/certifications",
    headers={
        "Authorization": "Bearer <token>",
    },
)
response.raise_for_status()
print(response.json())
go
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))
}
java
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());
    }
}
csharp
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
<?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;
ruby
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}"
rust
// 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

NameTypeDescription
agentId
required
string

Agent ID

Query parameters

NameTypeDescription
current_onlyboolean

Only certifications the gateway enforces from

validation_statusstring

valid, expired, not_yet_valid, revoked, invalid or untrusted_issuer

limitinteger

Page size (default 50, max 200)

offsetinteger

Page offset

Responses

200OK

application/json
  • correlation_idstring
  • itemsinternal_controlhttp.agentCertificationView[]
    Show properties

    Array of internal_controlhttp.agentCertificationView

    • agent_idstring
    • authorized_by_didstring
    • configuration_cidstring
    • configuration_standingobject

      ConfigurationStanding 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.KeyStanding

        • added_bystring

          Who added it; told only to an admin and the agent's operators

        • added_by_api_key_idstring

          The API key's public ID; told only to an admin and the agent's operators

        • added_by_emailstring

          Their 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 ofregistration_tokenapi_keycontrol_plane

        • configuration_cidstring

          ConfigurationCID is what its newest request's state gave, as a urn:cid; ConfigurationError why it gave none.

        • configuration_errorstring
        • didstring
        • last_seen_atstring
        • stateobject

          One ofcertifiedcordonedunknownidle

          Show properties

          object (enum) · one of certified, cordoned, unknown, idle

      • statusobject

        One ofcurrentpartly_drifteddriftedidle

        Show properties

        object (enum) · one of current, partly_drifted, drifted, idle

    • credential_idstring
    • credential_statusagentcertification.CredentialStatusMetadata[]
      Show properties

      Array of agentcertification.CredentialStatusMetadata

      • idstring
      • rawobject
        Show properties

        Map of any

      • status_list_credentialstring
      • status_list_indexstring
      • status_purposestring
      • typestring
    • credential_status_checked_atstring
    • currentboolean
    • issuer_didstring
    • observed_atstring
    • operating_profile_checkagentcertification.OperatingProfileCheck
      Show agentcertification.OperatingProfileCheck
      • attempted_atstring

        AttemptedAt is the latest check, decided or not, and ErrorCode why it could not decide; empty when it did.

      • checked_atstring

        CheckedAt is when Status was last decided. A check that cannot tell leaves it, and Status, as they were.

      • current_operating_profile_cidstring

        CurrentOperatingProfileCID is the profile the agent held when Status was last decided, as a urn:cid; empty when it had none.

      • error_codestring
      • statusagentcertification.OperatingProfileStatus

        One ofmatchmismatchunknown

    • operating_profile_cidstring
    • program_cidstring
    • source_refsagentcertification.SourceRefs
      Show agentcertification.SourceRefs
      • credential_idstring
      • source_cidstring
    • status_resolutionagentcertification.StatusResolution
      Show agentcertification.StatusResolution
      • checked_atstring
      • metadataobject
        Show properties

        Map of any

      • revokedboolean
    • valid_fromstring
    • valid_untilstring
    • validation_errorsagentcertification.ValidationError[]
      Show properties

      Array of agentcertification.ValidationError

      • codestring
      • fieldstring
      • messagestring
    • validation_statusagentcertification.ValidationStatus

      One ofvalidexpirednot_yet_validrevokedinvaliduntrusted_issuer

  • total_countinteger
Examplejson
{
  "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

application/json
  • codestring
  • correlation_idstring
  • messagestring
Examplejson
{
  "code": "string",
  "correlation_id": "string",
  "message": "string"
}

401Unauthorized

application/json
  • codestring
  • correlation_idstring
  • messagestring
Examplejson
{
  "code": "string",
  "correlation_id": "string",
  "message": "string"
}

403An API key bound to a project, or narrowed by scopes that leave out view_agent_certifications

application/json
  • codestring
  • correlation_idstring
  • messagestring
Examplejson
{
  "code": "string",
  "correlation_id": "string",
  "message": "string"
}

404agent_not_found

application/json
  • codestring
  • correlation_idstring
  • messagestring
Examplejson
{
  "code": "string",
  "correlation_id": "string",
  "message": "string"
}

500Internal Server Error

application/json
  • codestring
  • correlation_idstring
  • messagestring
Examplejson
{
  "code": "string",
  "correlation_id": "string",
  "message": "string"
}

503The certification store is not configured

application/json
  • codestring
  • correlation_idstring
  • messagestring
Examplejson
{
  "code": "string",
  "correlation_id": "string",
  "message": "string"
}