v1 vs v2 API Differences

This page summarises the breaking changes and improvements introduced in v2 compared to v1.

Base URL

Authentication

v2 no longer accepts the public client ID or anonymous (lack of auth headers) access. Private credentials (API key) are required for all requests.

Response envelope

All v2 responses are wrapped in a consistent envelope regardless of success or failure.

v1 responses are flat:

{
  "success": true,
  "serverDomain": "...",
  "notaryKeyFingerprint": "..."
}

v2 responses wrap the payload under data:

{
  "apiVersion": "v2.0",
  "success": true,
  "data": {
    "serverDomain": "...",
    "notaryKeyFingerprint": "..."
  }
}

Structured errors

v2 errors include a machine-readable code field alongside the human-readable message:

{
  "apiVersion": "v2.0",
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request: missing field `data`"
  }
}

Error codes returned by /verify: INVALID_REQUEST, INVALID_PRESENTATION, INTERNAL_SERVER_ERROR

Error codes returned by /prove: INVALID_REQUEST, INTERNAL_SERVER_ERROR

Strict request validation

v2 rejects requests that contain unknown fields or use snake_case field names, returning a 400 INVALID_REQUEST. All request body fields must be camelCase.

/verify: TLS timestamp

The v2 /verify response includes a new tlsTimestamp field — a Unix epoch timestamp (seconds) of when the TLS handshake occurred, as recorded by the notary. This can be used to establish when the proven data was retrieved.

/verify: Headers format

The headers arrays in the request and response objects changed format for consistency with /prove.

/prove: Default notary URL