API Overview

This page groups the externally relevant API surfaces by workflow rather than by internal service implementation.

Entitlement and run lifecycle API

These endpoints are used by the customer job during a normal entitled run:

Endpoint	Purpose	Typical caller
POST /api/entitlement/check	Confirms entitlement availability for a proposed run_id	Runner
POST /api/entitlement/consume	Consumes one run from the entitlement balance	Runner
POST /api/entitlement/run_start	Records run-start metadata such as hashes, image, and project ID	Runner
POST /api/entitlement/run_complete	Marks successful completion and returns the seal bundle	Runner

Seal verification API

These endpoints support verification and controlled reruns:

Endpoint	Purpose	Typical caller
POST /api/seal/verify	Verifies an uploaded seal.svg and returns verification data	User, operator, portal
POST /api/entitlement/redeem_seal_once	Grants a one-time rerun for a verified (principal, seal_id) pair	Authenticated user or operator

The one-time redemption flow is replay-resistant. A second attempt for the same (principal, seal_id) pair should return 409.

Admin issuance API

This endpoint is used by the partner or publisher side of the workflow:

Endpoint	Purpose	Typical caller
POST /api/entitlement/issue	Issues entitlement runs to a customer principal	Partner or admin operator

Authentication model

The current customer deployment path is identity-only:

• The job authenticates with Google identity
• The service uses the caller identity as the principal
• Customers do not manage long-lived entitlement tokens in the normal flow

For admin issuance, the current customer docs also reference an admin token header:

• X-GBX-ADMIN-TOKEN

What belongs in API docs versus product docs

Use the API docs to define:

• Endpoint purpose
• Auth expectations
• Required sequencing
• Expected status codes

Use product and trust docs to explain:

• Why the entitlement model exists
• What the seal means
• How rerun policy works in user terms

For status codes, see Error Codes.