Rest API’s

All Keylime APIs use REST (Representational State Transfer).

Check the Changelog section for the differences between versions

API versions

Changelog

Changes from v2.5 to v3.0

API version 3.0 introduces push-model attestation. Unlike previous versions where the verifier polls agents, in v3.0 agents initiate connections and submit attestation evidence to the verifier. The v3.0 endpoints are served by the verifier only; the push-model agent does not expose HTTP endpoints.

  • Added POST /v3/agents/{agent_id}/attestations endpoint to the verifier:

    • Allows agents to submit attestation capabilities (Phase 1 of push protocol)

    • Returns challenge nonce for TPM quote generation

  • Added PATCH /v3/agents/{agent_id}/attestations/latest endpoint:

    • Allows agents to submit attestation evidence (Phase 2 of push protocol)

    • Returns 202 Accepted for asynchronous verification

  • Added PATCH /v3/agents/{agent_id}/attestations/{index} endpoint:

    • Submit evidence for a specific attestation by index

  • Added GET /v3/agents/{agent_id}/attestations endpoint:

    • Lists all attestation records for an agent

  • Added GET /v3/agents/{agent_id}/attestations/latest endpoint:

    • Returns the most recent attestation for an agent, including verification status

  • Added GET /v3/agents/{agent_id}/attestations/{index} endpoint:

    • Returns a specific attestation by its index

  • Added POST /v3/sessions endpoint:

    • Creates a PoP authentication session and returns a challenge nonce for the agent

  • Added PATCH /v3/sessions/{session_id} endpoint:

    • Completes PoP authentication by submitting the TPM-signed challenge response

  • Introduced PoP (Proof of Possession) bearer token authentication for agent-to-verifier communication

API version 3.0 also introduces RFC 9110-compliant registrar routes:

  • Added GET /v3.0/ version root probe endpoint to the registrar, allowing clients to check whether the server supports API version 3.0.

  • Agent registration now uses POST /v3.0/agents/ (collection-level endpoint). The agent_id is sent in the JSON request body instead of the URL path.

  • Agent activation now uses POST /v3.0/agents/{agent_id}/activate instead of PUT, following correct HTTP method semantics.

  • Removed legacy backwards-compatibility routes from the registrar:

    • POST /agents/{agent_id} (use POST /agents/ instead)

    • PUT /agents/{agent_id}/activate (use POST /agents/{agent_id}/activate)

    • PUT /agents/{agent_id} (use POST /agents/{agent_id}/activate)

Changes from v2.4 to v2.5

API version 2.5 was first implemented in Keylime 7.14.0.

  • Modified POST /v2.5/verify/evidence endpoint:

    • Changed valid response field from integer (1/0) to boolean (true/false)

    • Added claims field to response containing verified claims

    • Added TEE (Trusted Execution Environment) verification support

  • Modified GET /v2.5/quotes/integrity endpoint:

    • enc_alg field in agent responses were modified to return explicit bit-length formats (e.g., rsa2048, rsa3072, ecc256, ecc384)

  • Server-side automatic normalization ensures backward compatibility:

    • rsa → rsa2048

    • ecc → ecc256

  • Enhanced GET /version endpoint to support API version negotiation:

    • Added supported_versions field containing an array of all API versions the agent supports

    • Retained supported_version field for backward compatibility (contains latest version)

    • Tenant and verifier now negotiate to use the highest mutually supported API version instead of blindly using the agent’s latest version

    • Prevents compatibility issues when newer agents communicate with older tenants/verifiers

  • Added attestation monitoring fields to GET /v2.5/agents/{agent_id} response:

    • attestation_status: Current attestation status ("PASS", "FAIL", or "PENDING")

    • attestation_period: Configured attestation interval derived from quote_interval

    • maximum_attestation_interval: Maximum time allowed between attestations in PUSH mode

Changes from v2.3 to v2.4

API version 2.4 was first implemented in Keylime 7.13.0.

  • Added POST /v2.4/verify/evidence experimental endpoint to the verifier:

    • Allows 3rd party verification of TPM attestation evidence (quotes, IMA logs, measured boot) against policies

    • Returns valid field (integer: 1 for valid, 0 for invalid) and failures array with validation errors

Changes from v2.2 to v2.3

API version 2.3 was first implemented in Keylime 7.12.0.

  • Added GET /v2.3/mbpolicies/{name} endpoint to the verifier

  • Added POST /v2.3/mbpolicies/{name} endpoint to the verifier

  • Added PUT /v2.3/mbpolicies/{name} endpoint to the verifier

  • Added DELETE /v2.3/mbpolicies/{name} endpoint to the verifier

  • Added GET /version endpoint to the registrar

Changes from v2.1 to v2.2

API version 2.2 was first implemented in Keylime 7.11.0.

  • Added GET /v2.2/verify/identity endpoint to the verifier

  • Added GET /v2.2/agent/info endpoint to the agent

Changes from v2.0 to v2.1

API version 2.1 was first implemented in Keylime 6.4.0.

  • Added ak_tpm field to POST /v2.1/agents/{agent_id:UUID} in verifier.

  • Added mtls_cert field to POST /v2.1/agents/{agent_id:UUID} in verifier.

  • Removed vmask parameter from GET /v2.1/quotes/integrity in agent

This removed the requirement for the verifier to connect to the registrar.

Changes from v1.0 to v2.0

API version 2.0 was first implemented in Keylime 6.3.0.

  • Added mTLS authentication to agent endpoints.

  • Added supported_version field to POST /v2.0/agents/{agent_id:UUID} in verifier.

  • Added mtls_cert field to POST/GET /v2.0/agents/{agent_id:UUID} in registrar.

  • Added /version endpoint to agent. Note that this endpoint is not implemented by all agents.

  • Dropped zlib encryption for quote field data in GET /v2.0/quotes/integrity/GET /v2.0/quotes/identity.

RESTful API for Keylime

Keylime API is versioned. More information can be found here: https://github.com/keylime/enhancements/blob/master/45_api_versioning.md

Warning

API version 1.0 will no longer be officially supported starting with Keylime 6.4.0.

General responses

ANY /

Generic fields in responses

Response JSON Object:

  • code (int) – HTTP status code

  • status (string) – textual context of that status

  • results (object) – Holds the actual data.