Certify an agent assessment

Ask for the AgentCertificationV1 an assessment's newest submission earned once every program control passed review. The review that leaves the submission passed asks for it already, so this is how to ask again when that failed. The request is the caller's sign-off: the Integrity Service signs the credential with the platform key on their token and names them authorizedBy, and it rests on each control's newest review of the submission. The caller administers programs, or still reviews the program and made one of the reviews the certification rests on, as a project's auditor issues its compliance credential, and never started the assessment or made the submission; the assessment's canCertify says which. Signing with the platform key also takes a role that may sign. The caller must still see the agent in the agent registry, and it must still be active. Governance records the credential once it has checked it certifies the assessment's agent, program version and the submission's pinned configuration. Asking again for a submission certified already returns its certification with 200, to its starter too, though they never issue it; a revoked one is never replaced, so certifying the agent again takes a new submission. Either way the certification is attached to the gateway on the caller's token, which the agent registry lets an administrator, an operator of the agent, or the reviewer it names as authorizedBy do, so the right it grants takes effect at once; gateway says how that went, and a failure there undoes nothing. The caller acts in person, or through their API key bound to no project with full access, or with the manage_programs scope to ask as an administrator or the review_agent_assessments scope to ask as a reviewer. A key signs with the platform key only if its scopes cover every permission of a role that may sign, and reads only agents its holder is bound to

posthttps://localhost:10001/api/v1/organizations/{orgId}/assessments/{assessmentId}/certifications

bash

curl --request POST \
  --url 'https://localhost:10001/api/v1/organizations/{orgId}/assessments/{assessmentId}/certifications' \
  --header 'Authorization: Bearer <token>'

javascript

const response = await fetch("https://localhost:10001/api/v1/organizations/{orgId}/assessments/{assessmentId}/certifications", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>"
  }
});

const data = await response.json();

typescript

interface CertificationResponse {
  agentName?: string;
  agentUrn?: string;
  assessmentUuid?: string;
  canRevoke?: boolean;
  configurationCid?: string;
  credential?: Record<string, unknown>;
  credentialId?: string;
  expiresAt?: string;
  gateway?: Record<string, unknown>;
  issuedAt?: string;
  issuedBy?: string;
  issuedByDid?: string;
  issuedByUserId?: string;
  profileCid?: string;
  programManifestCid?: string;
  programSlug?: string;
  programUuid?: string;
  provenance?: Record<string, unknown>;
  revoked?: boolean;
  revokedAt?: string;
  revokedBy?: string;
  revokedByDid?: string;
  revokedByUserId?: string;
  revokedReason?: string;
  sourceCid?: string;
  status?: "active" | "expired" | "revoked";
  submissionNumber?: number;
}

const response = await fetch("https://localhost:10001/api/v1/organizations/{orgId}/assessments/{assessmentId}/certifications", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>"
  }
});
if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);

const data: CertificationResponse = await response.json();

python

import requests

response = requests.post(
    "https://localhost:10001/api/v1/organizations/{orgId}/assessments/{assessmentId}/certifications",
    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.MethodPost, "https://localhost:10001/api/v1/organizations/{orgId}/assessments/{assessmentId}/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://localhost:10001/api/v1/organizations/{orgId}/assessments/{assessmentId}/certifications"))
            .header("Authorization", "Bearer <token>")
            .method("POST", 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.Post, "https://localhost:10001/api/v1/organizations/{orgId}/assessments/{assessmentId}/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://localhost:10001/api/v1/organizations/{orgId}/assessments/{assessmentId}/certifications');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    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://localhost:10001/api/v1/organizations/{orgId}/assessments/{assessmentId}/certifications")
request = Net::HTTP::Post.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()
        .post("https://localhost:10001/api/v1/organizations/{orgId}/assessments/{assessmentId}/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 JWT token.

Parameters

Path parameters

Name	Type	Description
`orgId` required	`string`	Organization ID or UUID (urn:uuid optional)
`assessmentId` required	`string`	Assessment UUID (urn:uuid optional)

Responses

200The submission's certification, recorded already, attached to the gateway again

application/json

agentNamestringread-only
The agent's display name in the agent registry when its assessment last read it; a label only, never part of the credential
agentUrnstringread-only
The credential's subject: the agent's registry ID
assessmentUuidstringread-only
urn:uuid form
canRevokebooleanread-only
Whether the caller may revoke it: it is not revoked, and they administer programs or are the reviewer who authorized it and still review its program; false for an API key that does not act as its holder
configurationCidstringread-only
The configuration it certifies, pinned by the submission
credentialobjectread-only
The signed credential, as issued
credentialIdstringread-only
The credential's urn:uuid, which identifies the certification
expiresAtstring<date-time>read-only
The credential's validUntil; absent when the program sets no term
gatewayobject
Issuing attaches the certification to the gateway, and revoking has the gateway read its status again; either way a failure there undoes nothing
Show properties
- configurationStatusstring (enum)
  How the agent's keys stand against the configuration it certifies, each by its newest request: current (every key seen lately runs it), partly_drifted (some do; the gateway refuses the rest), drifted (none do) or idle (no key seen lately). Set when attached or refreshed and valid: a certification the gateway won't honor has no keys standing against it
  One ofcurrentpartly_drifteddriftedidle
- currentboolean
  Whether the gateway enforces the agent's program from it. Set when attached or refreshed
- errorstring
  When failed: why, and what to do
- errorCodestring
  When failed: the gateway's error code, or control_plane_unavailable when it could not be reached
- operatingProfileStatusstring (enum)
  Whether the agent still holds the operating profile it certifies. Set when attached or refreshed
  One ofmatchmismatchunknown
- outcomestring (enum)
  attached or refreshed: the gateway holds it, as validationStatus says; not_attached: it never held this revoked certification; failed: it could not be updated, as error says
  One ofattachedrefreshednot_attachedfailed
- validationStatusstring (enum)
  The gateway's verification of it; it honors only a valid one. Set when attached or refreshed
  One ofvalidexpirednot_yet_validrevokedinvaliduntrusted_issuer
issuedAtstring<date-time>read-only
issuedBystringread-only
The program administrator who requested it
issuedByDidstringread-only
Verifiable actor, the credential's authorizedBy; issuedBy is the label
issuedByUserIdstringread-only
profileCidstringread-only
The operating profile it certifies the agent against, pinned by the submission; absent when none was
programManifestCidstringread-only
The program version it certifies against
programSlugstringread-only
The program the version belongs to
programUuidstringread-only
urn:uuid form
provenanceobjectread-only
Who certified what: the statements the credential's evidence names, read back from the submission it certifies. Only for a caller who may read its assessment: absent for one who only sees the agent, and for a key scoped to view_agent_certifications
Show properties
- declarationscore.CertificationDeclaration[]
  The declarations its evidence names, in the evidence's order
  Show properties
  Array of core.CertificationDeclaration
  controlsstring[]
  The control codes it covers, in the program's order
  documentCidstring
  urn:cid of the declaration document
  statementIdstring
  urn:cid of the governance statement it registered as
  submittedAtstring<date-time>
  submittedBystring
  submittedByDidstring
  submittedByUserIdstring
  uuidstring
  urn:uuid form
- reviewscore.ControlReview[]
  The review of each control it rests on, in the evidence's order, which is the program's
  Show properties
  Array of core.ControlReview
  controlCodestring
  documentCidstring
  urn:cid of the review document the Integrity Service stored
  evidenceCidstring
  urn:cid of the control's evidence the review judged; absent on reviews made before controls carried evidence
  outcomeobject
  One ofsatisfiednot_satisfiednot_applicable
  Show properties
  object (enum) · one of satisfied, not_satisfied, not_applicable
  reviewedAtstring<date-time>
  reviewedBystring
  reviewedByDidstring
  reviewedByUserIdstring
  statementstring
  statementIdstring
  urn:cid of the governance statement it registered as
  uuidstringread-only
  urn:uuid form
- submissionobject
  The submission it certifies
  Show properties
  documentCidstring
  urn:cid of the submission document
  numberinteger
  statementIdstring
  urn:cid of the governance statement it registered as
  submittedAtstring<date-time>
  submittedBystring
  submittedByDidstring
  submittedByUserIdstring
  uuidstring
  urn:uuid form
- unmatchedstring[]
  Statements its evidence names that are none of these, by urn:cid; never expected, and never hidden
revokedbooleanread-only
Set via the revoke endpoint
revokedAtstring<date-time>read-only
Set via the revoke endpoint
revokedBystringread-only
Set via the revoke endpoint
revokedByDidstringread-only
Verifiable actor; revokedBy is the label
revokedByUserIdstringread-only
Set via the revoke endpoint
revokedReasonstringread-only
Set via the revoke endpoint
sourceCidstringread-only
Where the Integrity Service stored the signed credential
statusobjectread-only
Computed on read: revoked, else expired once expiresAt passes, else active
One ofactiveexpiredrevoked
Show properties
object (enum) — Computed on read: revoked, else expired once expiresAt passes, else active · one of active, expired, revoked
submissionNumberintegerread-only
The submission it certifies

Examplejson

{
  "agentName": "string",
  "agentUrn": "string",
  "assessmentUuid": "string",
  "canRevoke": true,
  "configurationCid": "string",
  "credential": {},
  "credentialId": "string",
  "expiresAt": "2025-01-01T00:00:00Z",
  "gateway": {
    "configurationStatus": "current",
    "current": true,
    "error": "string",
    "errorCode": "string",
    "operatingProfileStatus": "match",
    "outcome": "attached",
    "validationStatus": "valid"
  },
  "issuedAt": "2025-01-01T00:00:00Z",
  "issuedBy": "string",
  "issuedByDid": "string",
  "issuedByUserId": "string",
  "profileCid": "string",
  "programManifestCid": "string",
  "programSlug": "string",
  "programUuid": "string",
  "provenance": {
    "declarations": [
      {
        "controls": [
          "string"
        ],
        "documentCid": "string",
        "statementId": "string",
        "submittedAt": "2025-01-01T00:00:00Z",
        "submittedBy": "string",
        "submittedByDid": "string",
        "submittedByUserId": "string",
        "uuid": "string"
      }
    ],
    "reviews": [
      {
        "controlCode": "string",
        "documentCid": "string",
        "evidenceCid": "string",
        "outcome": "satisfied",
        "reviewedAt": "2025-01-01T00:00:00Z",
        "reviewedBy": "string",
        "reviewedByDid": "string",
        "reviewedByUserId": "string",
        "statement": "string",
        "statementId": "string"
      }
    ],
    "submission": {
      "documentCid": "string",
      "number": 0,
      "statementId": "string",
      "submittedAt": "2025-01-01T00:00:00Z",
      "submittedBy": "string",
      "submittedByDid": "string",
      "submittedByUserId": "string",
      "uuid": "string"
    },
    "unmatched": [
      "string"
    ]
  },
  "revoked": true,
  "revokedAt": "2025-01-01T00:00:00Z",
  "revokedBy": "string",
  "revokedByDid": "string",
  "revokedByUserId": "string",
  "revokedReason": "string",
  "sourceCid": "string",
  "status": "active",
  "submissionNumber": 0
}

201Certification, with what attaching it to the gateway did

application/json

agentNamestringread-only
The agent's display name in the agent registry when its assessment last read it; a label only, never part of the credential
agentUrnstringread-only
The credential's subject: the agent's registry ID
assessmentUuidstringread-only
urn:uuid form
canRevokebooleanread-only
Whether the caller may revoke it: it is not revoked, and they administer programs or are the reviewer who authorized it and still review its program; false for an API key that does not act as its holder
configurationCidstringread-only
The configuration it certifies, pinned by the submission
credentialobjectread-only
The signed credential, as issued
credentialIdstringread-only
The credential's urn:uuid, which identifies the certification
expiresAtstring<date-time>read-only
The credential's validUntil; absent when the program sets no term
gatewayobject
Issuing attaches the certification to the gateway, and revoking has the gateway read its status again; either way a failure there undoes nothing
Show properties
- configurationStatusstring (enum)
  How the agent's keys stand against the configuration it certifies, each by its newest request: current (every key seen lately runs it), partly_drifted (some do; the gateway refuses the rest), drifted (none do) or idle (no key seen lately). Set when attached or refreshed and valid: a certification the gateway won't honor has no keys standing against it
  One ofcurrentpartly_drifteddriftedidle
- currentboolean
  Whether the gateway enforces the agent's program from it. Set when attached or refreshed
- errorstring
  When failed: why, and what to do
- errorCodestring
  When failed: the gateway's error code, or control_plane_unavailable when it could not be reached
- operatingProfileStatusstring (enum)
  Whether the agent still holds the operating profile it certifies. Set when attached or refreshed
  One ofmatchmismatchunknown
- outcomestring (enum)
  attached or refreshed: the gateway holds it, as validationStatus says; not_attached: it never held this revoked certification; failed: it could not be updated, as error says
  One ofattachedrefreshednot_attachedfailed
- validationStatusstring (enum)
  The gateway's verification of it; it honors only a valid one. Set when attached or refreshed
  One ofvalidexpirednot_yet_validrevokedinvaliduntrusted_issuer
issuedAtstring<date-time>read-only
issuedBystringread-only
The program administrator who requested it
issuedByDidstringread-only
Verifiable actor, the credential's authorizedBy; issuedBy is the label
issuedByUserIdstringread-only
profileCidstringread-only
The operating profile it certifies the agent against, pinned by the submission; absent when none was
programManifestCidstringread-only
The program version it certifies against
programSlugstringread-only
The program the version belongs to
programUuidstringread-only
urn:uuid form
provenanceobjectread-only
Who certified what: the statements the credential's evidence names, read back from the submission it certifies. Only for a caller who may read its assessment: absent for one who only sees the agent, and for a key scoped to view_agent_certifications
Show properties
- declarationscore.CertificationDeclaration[]
  The declarations its evidence names, in the evidence's order
  Show properties
  Array of core.CertificationDeclaration
  controlsstring[]
  The control codes it covers, in the program's order
  documentCidstring
  urn:cid of the declaration document
  statementIdstring
  urn:cid of the governance statement it registered as
  submittedAtstring<date-time>
  submittedBystring
  submittedByDidstring
  submittedByUserIdstring
  uuidstring
  urn:uuid form
- reviewscore.ControlReview[]
  The review of each control it rests on, in the evidence's order, which is the program's
  Show properties
  Array of core.ControlReview
  controlCodestring
  documentCidstring
  urn:cid of the review document the Integrity Service stored
  evidenceCidstring
  urn:cid of the control's evidence the review judged; absent on reviews made before controls carried evidence
  outcomeobject
  One ofsatisfiednot_satisfiednot_applicable
  Show properties
  object (enum) · one of satisfied, not_satisfied, not_applicable
  reviewedAtstring<date-time>
  reviewedBystring
  reviewedByDidstring
  reviewedByUserIdstring
  statementstring
  statementIdstring
  urn:cid of the governance statement it registered as
  uuidstringread-only
  urn:uuid form
- submissionobject
  The submission it certifies
  Show properties
  documentCidstring
  urn:cid of the submission document
  numberinteger
  statementIdstring
  urn:cid of the governance statement it registered as
  submittedAtstring<date-time>
  submittedBystring
  submittedByDidstring
  submittedByUserIdstring
  uuidstring
  urn:uuid form
- unmatchedstring[]
  Statements its evidence names that are none of these, by urn:cid; never expected, and never hidden
revokedbooleanread-only
Set via the revoke endpoint
revokedAtstring<date-time>read-only
Set via the revoke endpoint
revokedBystringread-only
Set via the revoke endpoint
revokedByDidstringread-only
Verifiable actor; revokedBy is the label
revokedByUserIdstringread-only
Set via the revoke endpoint
revokedReasonstringread-only
Set via the revoke endpoint
sourceCidstringread-only
Where the Integrity Service stored the signed credential
statusobjectread-only
Computed on read: revoked, else expired once expiresAt passes, else active
One ofactiveexpiredrevoked
Show properties
object (enum) — Computed on read: revoked, else expired once expiresAt passes, else active · one of active, expired, revoked
submissionNumberintegerread-only
The submission it certifies

Examplejson

{
  "agentName": "string",
  "agentUrn": "string",
  "assessmentUuid": "string",
  "canRevoke": true,
  "configurationCid": "string",
  "credential": {},
  "credentialId": "string",
  "expiresAt": "2025-01-01T00:00:00Z",
  "gateway": {
    "configurationStatus": "current",
    "current": true,
    "error": "string",
    "errorCode": "string",
    "operatingProfileStatus": "match",
    "outcome": "attached",
    "validationStatus": "valid"
  },
  "issuedAt": "2025-01-01T00:00:00Z",
  "issuedBy": "string",
  "issuedByDid": "string",
  "issuedByUserId": "string",
  "profileCid": "string",
  "programManifestCid": "string",
  "programSlug": "string",
  "programUuid": "string",
  "provenance": {
    "declarations": [
      {
        "controls": [
          "string"
        ],
        "documentCid": "string",
        "statementId": "string",
        "submittedAt": "2025-01-01T00:00:00Z",
        "submittedBy": "string",
        "submittedByDid": "string",
        "submittedByUserId": "string",
        "uuid": "string"
      }
    ],
    "reviews": [
      {
        "controlCode": "string",
        "documentCid": "string",
        "evidenceCid": "string",
        "outcome": "satisfied",
        "reviewedAt": "2025-01-01T00:00:00Z",
        "reviewedBy": "string",
        "reviewedByDid": "string",
        "reviewedByUserId": "string",
        "statement": "string",
        "statementId": "string"
      }
    ],
    "submission": {
      "documentCid": "string",
      "number": 0,
      "statementId": "string",
      "submittedAt": "2025-01-01T00:00:00Z",
      "submittedBy": "string",
      "submittedByDid": "string",
      "submittedByUserId": "string",
      "uuid": "string"
    },
    "unmatched": [
      "string"
    ]
  },
  "revoked": true,
  "revokedAt": "2025-01-01T00:00:00Z",
  "revokedBy": "string",
  "revokedByDid": "string",
  "revokedByUserId": "string",
  "revokedReason": "string",
  "sourceCid": "string",
  "status": "active",
  "submissionNumber": 0
}

400Bad request - The assessment has not passed, the agent is not active, or the Integrity Service cannot certify the submission

application/json

errorstring

Examplejson

{
  "error": "Invalid request body"
}

401Unauthorized - Authentication required

application/json

errorstring

Examplejson

{
  "error": "Invalid request body"
}

403Forbidden - Neither administers programs nor made a review the certification rests on, started the assessment or made the submission of one not certified yet, an API key with neither full access nor the scope of either, a project-bound key, or the agent registry or the Integrity Service refuses the caller

application/json

errorstring

Examplejson

{
  "error": "Invalid request body"
}

404Assessment or agent not found, or not visible to the caller

application/json

errorstring

Examplejson

{
  "error": "Invalid request body"
}

409The submission's certification was revoked

application/json

errorstring

Examplejson

{
  "error": "Invalid request body"
}

500Internal server error

application/json

errorstring

Examplejson

{
  "error": "Invalid request body"
}

503The agent registry is unavailable

application/json

errorstring

Examplejson

{
  "error": "Invalid request body"
}