Get agent
Readable by an admin and by users bound to the agent, and by their API key bound to no project with full access or the submit_agent_assessments scope. Governance Service's service account can read it too, to check the agent is still active before certifying it. Each key says how it joined the agent; who added it (added_by, added_by_email, added_by_api_key_id) goes only to an admin and the agent's operators.
https://<host>/api/v1/agents/{agentId}curl --request GET \
--url 'https://<host>/api/v1/agents/{agentId}' \
--header 'Authorization: Bearer <token>'const response = await fetch("https://<host>/api/v1/agents/{agentId}", {
method: "GET",
headers: {
"Authorization": "Bearer <token>"
}
});
const data = await response.json();interface GetAgentResponse {
agent?: Record<string, unknown>;
correlation_id?: string;
keys?: Record<string, unknown>[];
projects?: Record<string, unknown>[];
users?: Record<string, unknown>[];
}
const response = await fetch("https://<host>/api/v1/agents/{agentId}", {
method: "GET",
headers: {
"Authorization": "Bearer <token>"
}
});
if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);
const data: GetAgentResponse = await response.json();import requests
response = requests.get(
"https://<host>/api/v1/agents/{agentId}",
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}", 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}"))
.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}");
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}');
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}")
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}")
.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 |
Responses
200OK
agentgithub_com_eqtylab_gateway_control-plane_service_internal_discovery.AgentSummaryShow github_com_eqtylab_gateway_control-plane_service_internal_discovery.AgentSummary
active_key_countintegeractive_user_binding_countintegeragent_idstringapp_typestringbadgesgithub_com_eqtylab_gateway_control-plane_service_internal_discovery.AgentBadge[]Show properties
Array of
github_com_eqtylab_gateway_control-plane_service_internal_discovery.AgentBadgedescriptionstringfirst_observed_atstringkeystringlabelstringlast_observed_atstringmetadataobjectShow properties
Map of
anymetadata_typestringplugin_idstringstatusstringsubject_didstring
created_atstringdid_sourcestringdisplay_namestringframeworkobjectFramework is the framework named by the definition the agent's newest state names, as the definition gives it, read from the verified state rather than the app type a request declares. It is nil when the newest state names no definition (another app type, or recorded before the gateway recorded definitions) or the gateway couldn't record the definition's framework.
Show properties
namestringpackagesobjectShow properties
Map of
string
last_audit_atstringprimary_didstringprimary_user_display_namestringstatusstringthroughputinteger[]total_audit_eventsintegerupdated_atstring
correlation_idstringkeysgithub_com_eqtylab_gateway_control-plane_service_internal_discovery.AgentKey[]Show properties
Array of
github_com_eqtylab_gateway_control-plane_service_internal_discovery.AgentKeyadded_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 its agent: registration_token, api_key or control_plane; empty when no record of it survives. AddedBy is the subject of whoever added it, the registering principal or the admin, and AddedByAPIKeyID the API key's public ID.
One of
registration_tokenapi_keycontrol_planecreated_atstringdidstringstatusstringupdated_atstring
projectsgithub_com_eqtylab_gateway_control-plane_service_internal_discovery.AgentProject[]Show properties
Array of
github_com_eqtylab_gateway_control-plane_service_internal_discovery.AgentProjectproject_urnstringproject_uuidstringvalid_fromstringvalid_untilstringvalidation_statusstring
usersgithub_com_eqtylab_gateway_control-plane_service_internal_discovery.AgentUser[]Show properties
Array of
github_com_eqtylab_gateway_control-plane_service_internal_discovery.AgentUsercreated_atstringdisplay_namestringemailstringexternal_subjectstringrolestringstatusstringupdated_atstring
{
"agent": {
"active_key_count": 0,
"active_user_binding_count": 0,
"agent_id": "string",
"app_type": "string",
"badges": [
{
"description": "string",
"first_observed_at": "string",
"key": "string",
"label": "string",
"last_observed_at": "string",
"metadata": {
"key": null
},
"metadata_type": "string",
"plugin_id": "string",
"status": "string",
"subject_did": "string"
}
],
"created_at": "string",
"did_source": "string",
"display_name": "string",
"framework": {
"name": "string",
"packages": {
"key": "string"
}
},
"last_audit_at": "string",
"primary_did": "string",
"primary_user_display_name": "string",
"status": "string",
"throughput": [
0
],
"total_audit_events": 0,
"updated_at": "string"
},
"correlation_id": "string",
"keys": [
{
"added_by": "string",
"added_by_api_key_id": "string",
"added_by_email": "string",
"added_via": "registration_token",
"created_at": "string",
"did": "string",
"status": "string",
"updated_at": "string"
}
],
"projects": [
{
"project_urn": "string",
"project_uuid": "string",
"valid_from": "string",
"valid_until": "string",
"validation_status": "string"
}
],
"users": [
{
"created_at": "string",
"display_name": "string",
"email": "string",
"external_subject": "string",
"role": "string",
"status": "string",
"updated_at": "string"
}
]
}401Unauthorized
codestringcorrelation_idstringmessagestring
{
"code": "string",
"correlation_id": "string",
"message": "string"
}403Forbidden
codestringcorrelation_idstringmessagestring
{
"code": "string",
"correlation_id": "string",
"message": "string"
}404Not Found
codestringcorrelation_idstringmessagestring
{
"code": "string",
"correlation_id": "string",
"message": "string"
}500Internal Server Error
codestringcorrelation_idstringmessagestring
{
"code": "string",
"correlation_id": "string",
"message": "string"
}502Auth Service could not be asked whether a caller with no binding holds certify_agents
codestringcorrelation_idstringmessagestring
{
"code": "string",
"correlation_id": "string",
"message": "string"
}