EQTY LabDocs

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.

posthttps://<host>/v1/agents/registrations
bash
curl --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"}'
javascript
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();
typescript
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();
python
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())
go
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))
}
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>/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());
    }
}
csharp
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
<?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;
ruby
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}"
rust
// 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

application/json
  • agent_idstring

    AgentID 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_typestring
  • didstring
  • did_sourcestring

    Type of integrity signer used to create the did (Yubi, VComp, etc)

  • display_namestring
  • provisioning_tokenstring
Examplejson
{
  "agent_id": "string",
  "app_type": "string",
  "did": "string",
  "did_source": "string",
  "display_name": "string",
  "provisioning_token": "string"
}

Responses

200OK

application/json
  • agent_idstring
  • agent_statusstring
  • correlation_idstring
  • key_statusstring
  • registered_atinteger
  • registration_resultobject

    One ofcreatedupdatednoop

    Show properties

    object (enum) · one of created, updated, noop

  • vcany
Examplejson
{
  "agent_id": "string",
  "agent_status": "string",
  "correlation_id": "string",
  "key_status": "string",
  "registered_at": 0,
  "registration_result": "created",
  "vc": null
}

201Created

application/json
  • agent_idstring
  • agent_statusstring
  • correlation_idstring
  • key_statusstring
  • registered_atinteger
  • registration_resultobject

    One ofcreatedupdatednoop

    Show properties

    object (enum) · one of created, updated, noop

  • vcany
Examplejson
{
  "agent_id": "string",
  "agent_status": "string",
  "correlation_id": "string",
  "key_status": "string",
  "registered_at": 0,
  "registration_result": "created",
  "vc": null
}

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

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

409Conflict

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

502Bad Gateway

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