API Reference

2.1 Introduction

The Mintall Verification API is a public surface for verifiers and agents to retrieve Mintall Certificate for Product (MC4P) and reproduce key verification checks in a deterministic way. It assumes the terminology and trust model defined in the Verification Specification.

The offering is intentionally small:

• Fetch the full JSON-LD certificate for caching/offline use.
• Discover signing keys (JWKS) to verify proof.jwt offline.
• Verify domain/context authorization server-side when you need a fast, consistent check.

The API MUST NOT be treated as an authoritative source of image integrity or provenance; registry and provenance claims MUST be validated against the C2PA manifest extracted from the evaluated image bytes.

Inputs (Verification Context)

The following inputs are required to perform deterministic verification checks as defined in this API and the Verification Specification.

• image_id: UUID for the certified image (Mintall asset identifier).
• current_domain: The domain where the agent observed the product page / certificate usage (hostname only). (For server calls this is sent as domain.)

2.2 Endpoint Reference

Complete API specification for all verification endpoints. Each endpoint includes required request format, response schema, authentication, error codes, and use cases.

// No request body for GET

{
  "@context": "https://schema.org",
  "@type": "DigitalDocument",
  "imageId": "5b749adb-f198-428f-a7af-4323f9c16297",
  "verification": {
    "authorizedDomains": ["merchant.example"],
    "domainVerified": true,
    "hasSignature": true
  }
}

// No request body for GET

{
  "@context": ["https://schema.org", "..."],
  "@type": "MediaObject",
  "proof": {
    "type": "JwtProof2020",
    "jwt": "eyJhbGciOiJSUzI1NiIsImtpZCI6..."
  },
  "contentCredentials": {
    "dateIssued": "2025-12-14T17:12:00Z",
    "lastUpdated": "2025-12-14T17:12:00Z"
  }
}

// No request body for GET

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "mintall-2025-01",
      "use": "sig",
      "alg": "RS256",
      "n": "...",
      "e": "AQAB"
    }
  ]
}

{
  "domain": "merchant.example"
}

{
  "verified": true,
  "imageId": "5b749adb-f198-428f-a7af-4323f9c16297",
  "authorizedDomain": "merchant.example",
  "currentDomain": "merchant.example",
  "checks": {
    "domainMatches": true,
    "certificateConsistency": true
  },
  "warnings": [],
  "errors": []
}

2.3 Context Verification

Context verification ensures a certificate is valid for the specific domain and context where it was observed. The POST /api/v1/mc4p/{image_id}/verify endpoint supports multiple verification modes by including optional fields in the request body:

• Domain authorization only (server-assisted): Only pass domain to check domain authorization (see section 2.2.4).
• Product ID check: Add verifyField: "productId" to validate product binding.
• Custom field check: Add verifyField and fieldValue for other bound fields.

{
  "domain": "merchant.example",
  "verifyField": "productId",
  "fieldValue": "gid://shopify/Product/1234567890"
}

{
  "verified": true,
  "imageId": "5b749adb-f198-428f-a7af-4323f9c16297",
  "checks": {
    "domainMatches": true
  },
  "warnings": [],
  "errors": []
}

{
  "domain": "merchant.example",
  "verifyField": "productUrl",
  "fieldValue": "https://merchant.example/products/modern-lamp"
}

{
  "verified": true,
  "imageId": "5b749adb-f198-428f-a7af-4323f9c16297",
  "checks": {
    "domainMatches": true
  },
  "warnings": [],
  "errors": []
}

2.4 Error Codes

The following error codes are canonical error codes used by the Verification API. Individual endpoints may return a subset.

• 400 Bad Request: Invalid payload or missing required fields.
• 402 Payment Required: Certificate paused due to entitlement or plan limits.
• 403 Forbidden: Domain not authorized for this certificate.
• 404 Not Found: No certificate exists for the specified image_id.
• 412 Precondition Failed: Domain verification required (when enforcement is enabled).
• 422 Unprocessable Entity: Context mismatch or unsupported verification field.
• 500 Internal Server Error: Temporary server failure.

2.5 Caching and Offline Use

JWKS responses are cacheable and SHOULD be reused for offline JWT verification. Verifiers SHOULD cache MC4P Certificates when possible and treat them as immutable for the duration of their validity window.

Offline verification requires:

• The certificate JSON-LD
• The corresponding image bytes
• A cached JWKS
• Observed context values (domain, and any bound field values the agent intends to verify)

C2PA verification MUST be performed against the image bytes being evaluated.

2.6 Verification Profiles (Non-Normative)

Agents may implement different verification profiles depending on use case:

• Minimal: JWT + domain authorization (no image provenance checks)
• Standard: Minimal + context binding (for example productId/productUrl checks)
• Full: Standard + C2PA verification against evaluated image bytes

JWT Verification Requirements:

• For Standard and Full verification profiles, successful verification of the JWT proof using JWKS is REQUIRED.
• A certificate whose JWT signature cannot be verified, is missing, or fails validation MUST be treated as untrusted for Standard and Full profiles, regardless of server-assisted verification results.