EQTY LabDocs

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.

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

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

response = requests.get(
    "https://<host>/api/v1/agents/{agentId}",
    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}", 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}"))
            .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}");
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}');
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}")
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}")
        .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

Responses

200OK

application/json
  • agentgithub_com_eqtylab_gateway_control-plane_service_internal_discovery.AgentSummary
    Show github_com_eqtylab_gateway_control-plane_service_internal_discovery.AgentSummary
    • active_key_countinteger
    • active_user_binding_countinteger
    • agent_idstring
    • app_typestring
    • badgesgithub_com_eqtylab_gateway_control-plane_service_internal_discovery.AgentBadge[]
      Show properties

      Array of github_com_eqtylab_gateway_control-plane_service_internal_discovery.AgentBadge

      • descriptionstring
      • first_observed_atstring
      • keystring
      • labelstring
      • last_observed_atstring
      • metadataobject
        Show properties

        Map of any

      • metadata_typestring
      • plugin_idstring
      • statusstring
      • subject_didstring
    • created_atstring
    • did_sourcestring
    • display_namestring
    • frameworkobject

      Framework 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
      • namestring
      • packagesobject
        Show properties

        Map of string

    • last_audit_atstring
    • primary_didstring
    • primary_user_display_namestring
    • statusstring
    • throughputinteger[]
    • total_audit_eventsinteger
    • updated_atstring
  • correlation_idstring
  • keysgithub_com_eqtylab_gateway_control-plane_service_internal_discovery.AgentKey[]
    Show properties

    Array of github_com_eqtylab_gateway_control-plane_service_internal_discovery.AgentKey

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

    • created_atstring
    • didstring
    • statusstring
    • updated_atstring
  • projectsgithub_com_eqtylab_gateway_control-plane_service_internal_discovery.AgentProject[]
    Show properties

    Array of github_com_eqtylab_gateway_control-plane_service_internal_discovery.AgentProject

    • project_urnstring
    • project_uuidstring
    • valid_fromstring
    • valid_untilstring
    • validation_statusstring
  • usersgithub_com_eqtylab_gateway_control-plane_service_internal_discovery.AgentUser[]
    Show properties

    Array of github_com_eqtylab_gateway_control-plane_service_internal_discovery.AgentUser

    • created_atstring
    • display_namestring
    • emailstring
    • external_subjectstring
    • rolestring
    • statusstring
    • updated_atstring
Examplejson
{
  "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

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

403Forbidden

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

404Not 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"
}

502Auth Service could not be asked whether a caller with no binding holds certify_agents

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