Register agent signing key
Registers an agent's DID and returns a verifiable credential for it. Authenticate with either a single-use Control Plane registration token in the body's provisioning_token, which also names the agent_id, or a Guardian Platform API key in the Authorization header when Auth Service enrollment is configured. With an API key, provisioning_token must be empty, and agent_id is optional: absent creates an agent, present adds the DID to that agent. Returns 201 when the registration creates the key, and 200 when it updates or repeats an existing one. Returns 404 when registration, or API-key registration, is not enabled.
https://<host>/v1/agents/registrationscurl --request POST \
--url 'https://<host>/v1/agents/registrations' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{"agent_id":"string","app_type":"string","did":"string","did_source":"string","display_name":"string","provisioning_token":"string"}'const response = await fetch("https://<host>/v1/agents/registrations", {
method: "POST",
headers: {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
},
body: JSON.stringify({
"agent_id": "string",
"app_type": "string",
"did": "string",
"did_source": "string",
"display_name": "string",
"provisioning_token": "string"
})
});
const data = await response.json();interface RegistrationResponseBody {
agent_id?: string;
agent_status?: string;
correlation_id?: string;
key_status?: string;
registered_at?: number;
registration_result?: "created" | "updated" | "noop";
vc?: unknown;
}
const response = await fetch("https://<host>/v1/agents/registrations", {
method: "POST",
headers: {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
},
body: JSON.stringify({
"agent_id": "string",
"app_type": "string",
"did": "string",
"did_source": "string",
"display_name": "string",
"provisioning_token": "string"
})
});
if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);
const data: RegistrationResponseBody = await response.json();import requests
response = requests.post(
"https://<host>/v1/agents/registrations",
headers={
"Authorization": "Bearer <token>",
"Content-Type": "application/json",
},
json={
"agent_id": "string",
"app_type": "string",
"did": "string",
"did_source": "string",
"display_name": "string",
"provisioning_token": "string",
},
)
response.raise_for_status()
print(response.json())package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
body := strings.NewReader(`{
"agent_id": "string",
"app_type": "string",
"did": "string",
"did_source": "string",
"display_name": "string",
"provisioning_token": "string"
}`)
req, err := http.NewRequest(http.MethodPost, "https://<host>/v1/agents/registrations", body)
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "Bearer <token>")
req.Header.Set("Content-Type", "application/json")
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>/v1/agents/registrations"))
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.method("POST", HttpRequest.BodyPublishers.ofString("""
{
"agent_id": "string",
"app_type": "string",
"did": "string",
"did_source": "string",
"display_name": "string",
"provisioning_token": "string"
}
"""))
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode() + " " + response.body());
}
}using System.Net.Http.Headers;
using System.Text;
using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Post, "https://<host>/v1/agents/registrations");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", "<token>");
request.Content = new StringContent("""
{
"agent_id": "string",
"app_type": "string",
"did": "string",
"did_source": "string",
"display_name": "string",
"provisioning_token": "string"
}
""", Encoding.UTF8, "application/json");
using var response = await client.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");<?php
$ch = curl_init('https://<host>/v1/agents/registrations');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer <token>',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => <<<'JSON'
{
"agent_id": "string",
"app_type": "string",
"did": "string",
"did_source": "string",
"display_name": "string",
"provisioning_token": "string"
}
JSON,
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>/v1/agents/registrations")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer <token>"
request["Content-Type"] = "application/json"
request.body = <<~'JSON'
{
"agent_id": "string",
"app_type": "string",
"did": "string",
"did_source": "string",
"display_name": "string",
"provisioning_token": "string"
}
JSON
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 (features "json"), serde_json, tokio (features "full")
use serde_json::json;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let response = reqwest::Client::new()
.post("https://<host>/v1/agents/registrations")
.header("Authorization", "Bearer <token>")
.json(&json!({
"agent_id": "string",
"app_type": "string",
"did": "string",
"did_source": "string",
"display_name": "string",
"provisioning_token": "string"
}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Ok(())
}Authorizations
ApiKeyAuth· API key in header "Authorization" — Type "Bearer" followed by a space and a Guardian Platform API key (ak_…). Accepted only for agent registration, when the gateway is configured to enroll agents through Auth Service. Registration with a registration token sends no Authorization header.- Or no authentication.
Request bodyrequired
Registration payload
agent_idstringAgentID is required with a provisioning token. With an API key it is optional: absent creates an agent, present adds the DID to that agent.
app_typestringdidstringdid_sourcestringType of integrity signer used to create the did (Yubi, VComp, etc)
display_namestringprovisioning_tokenstring
{
"agent_id": "string",
"app_type": "string",
"did": "string",
"did_source": "string",
"display_name": "string",
"provisioning_token": "string"
}Responses
200OK
agent_idstringagent_statusstringcorrelation_idstringkey_statusstringregistered_atintegerregistration_resultobjectOne of
createdupdatednoopShow properties
object (enum)· one of created, updated, noopvcany
{
"agent_id": "string",
"agent_status": "string",
"correlation_id": "string",
"key_status": "string",
"registered_at": 0,
"registration_result": "created",
"vc": null
}201Created
agent_idstringagent_statusstringcorrelation_idstringkey_statusstringregistered_atintegerregistration_resultobjectOne of
createdupdatednoopShow properties
object (enum)· one of created, updated, noopvcany
{
"agent_id": "string",
"agent_status": "string",
"correlation_id": "string",
"key_status": "string",
"registered_at": 0,
"registration_result": "created",
"vc": null
}400Bad Request
codestringcorrelation_idstringmessagestring
{
"code": "string",
"correlation_id": "string",
"message": "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"
}409Conflict
codestringcorrelation_idstringmessagestring
{
"code": "string",
"correlation_id": "string",
"message": "string"
}500Internal Server Error
codestringcorrelation_idstringmessagestring
{
"code": "string",
"correlation_id": "string",
"message": "string"
}502Bad Gateway
codestringcorrelation_idstringmessagestring
{
"code": "string",
"correlation_id": "string",
"message": "string"
}