Canonicalize. Sign.
Issue. Resolve.

01 / AUTHENTICATION

Bearer keys, scoped to one organization.

Create a key inside your authenticated dashboard, store it in a secret manager, and pass it in the Authorization header. The registry displays each secret once and stores only its SHA-256 hash.

Authorization: Bearer tec_live_••••••••••••

02 / CANONICALIZE

POST /api/v1/credentials/canonicalize

Normalizes the submitted evidence and returns the exact UTF-8 JSON string the laboratory must sign. Do not reserialize or reformat that string before signing.

curl https://tecrid.com/api/v1/credentials/canonicalize \
  -H "Authorization: Bearer $TEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "sampleName": "Organic cacao powder",
  "lotNumber": "C-240518",
  "matrix": "Food · Powder",
  "method": "ICP-MS",
  "submittingParty": "Example Brand",
  "releasedAt": "2026-08-28",
  "sourceDocument": {
    "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "filename": "laboratory-report.pdf",
    "reportNumber": "LAB-240518"
  },
  "publish": true,
  "results": [
    { "analyte": "Lead", "symbol": "Pb", "resultText": "42", "unit": "µg/kg", "loqText": "10" }
  ]
}'

03 / ISSUE

POST /api/v1/credentials

Creates a private draft when publish is false. Public issuance additionally requires verified laboratory status, a reviewed key, and a valid Ed25519 signature over the canonical payload. Successful issuance returns a permanent TECRID.

For a historical PDF, include sourceDocument. Its SHA-256 fingerprint, report reference, submitting party, and release date become part of the signed payload; the private PDF itself is not exposed by the public API.

curl https://tecrid.com/api/v1/credentials \
  -H "Authorization: Bearer $TEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sampleName": "Organic cacao powder",
    "productSku": "CACAO-12OZ",
    "lotNumber": "C-240518",
    "matrix": "Food · Powder",
    "method": "ICP-MS",
    "submittingParty": "Example Brand",
    "releasedAt": "2026-08-28",
    "sourceDocument": {
      "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
      "filename": "laboratory-report.pdf",
      "reportNumber": "LAB-240518"
    },
    "publish": true,
    "proof": {
      "keyId": "lab.example/key/2026-01",
      "algorithm": "Ed25519",
      "signature": "BASE64URL_SIGNATURE"
    },
    "results": [
      { "analyte": "Lead", "symbol": "Pb", "resultText": "42", "unit": "µg/kg", "loqText": "10" }
    ]
  }'

03A / REPORT MARK

Reserve. Render. Fingerprint. Sign. Finalize.

A laboratory cannot add an identifier after hashing the final PDF. Reserve the TECRID first, place the returned human-readable identifier and resolver URL or QR data into the report template, then hash and sign that finished PDF during finalization.

POST /api/v1/report-reservations

curl https://tecrid.com/api/v1/report-reservations \
  -H "Authorization: Bearer $LAB_TEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "productName": "Organic cacao powder",
    "productSku": "CACAO-12OZ",
    "laboratoryReportNumber": "LAB-240518",
    "sourceSystem": "labware",
    "routingToken": "tec_route_••••••••••••"
  }'

The response includes reportMark.templateFields.tecrid_identifier, tecrid_resolver_url, and qrData. Before finalization, the resolver shows an explicit reserved—not issued—state.

POST /api/v1/report-reservations/:id/finalize

curl https://tecrid.com/api/v1/report-reservations/$RESERVATION_ID/finalize \
  -H "Authorization: Bearer $LAB_TEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sampleName": "Organic cacao powder",
    "productSku": "CACAO-12OZ",
    "visibility": "controlled",
    "publish": true,
    "sourceDocument": {
      "sha256": "SHA256_OF_FINAL_TECRID_MARKED_PDF",
      "filename": "final-report.pdf",
      "reportNumber": "LAB-240518"
    },
    "proof": {
      "keyId": "lab.example/key/2026-01",
      "algorithm": "Ed25519",
      "signature": "BASE64URL_SIGNATURE"
    },
    "results": [
      { "analyte": "Lead", "resultText": "42", "unit": "µg/kg" }
    ]
  }'

Successful finalization issues the preprinted TECRID, preserves the final PDF fingerprint in the signed payload, creates the brand or supplier's full controller receipt, and fans out narrower packages to any active certifier, retailer, or government grants.

04 / LIST

GET /api/v1/credentials

Returns up to 100 credentials for the organization associated with the bearer key, newest first.

curl https://tecrid.com/api/v1/credentials \ -H "Authorization: Bearer $TEC_API_KEY"

05 / RESOLVE

GET /api/v1/credentials/:identifier

Public, no API key required. A public credential returns its results and complete proof bundle. A controlled credential returns only its resolver envelope—issuer, status, fingerprint, and version metadata—while results, canonical payloads, and signed payload remain withheld.

curl https://tecrid.com/api/v1/credentials/TECRID%C2%B7YOUR-LAB-26-XXXXXXXX

06 / CORRECT OR REVOKE

POST /api/v1/credentials/:tecrid/versions

Corrections and revocations append a new signed version. They never erase the prior fingerprint. First post the proposed revision to /:tecrid/canonicalize, sign the returned payload, then submit the same revision with its proof.

{
  "action": "revoke",
  "reason": "Sample identity could not be sustained after chain-of-custody review.",
  "proof": {
    "keyId": "lab.example/key/2026-01",
    "algorithm": "Ed25519",
    "signature": "BASE64URL_SIGNATURE"
  }
}

07 / CONTROLLED ROUTING

Issue once. Deliver only to active grants.

A certifier, retailer, or government workspace requests a SKU and result scope. The brand or ingredient supplier may approve a narrower grant, then creates a show-once tec_route_… token for one verified laboratory. TECRID stores only its SHA-256 hash.

The laboratory can attach the token to controlled issuance. The registry verifies the laboratory signature, finds the active recipient grants for that SKU, and freezes a separate fingerprinted view for each recipient.

curl https://tecrid.com/api/v1/credentials \
  -H "Authorization: Bearer $LAB_TEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sampleName": "Organic cacao powder",
    "productSku": "CACAO-12OZ",
    "lotNumber": "C-240518",
    "visibility": "controlled",
    "publish": true,
    "routingToken": "tec_route_••••••••••••",
    "proof": {
      "keyId": "lab.example/key/2026-01",
      "algorithm": "Ed25519",
      "signature": "BASE64URL_SIGNATURE"
    },
    "results": [
      { "analyte": "Lead", "resultText": "42", "unit": "µg/kg" }
    ]
  }'

POST /api/v1/routing/deliveries · retry without reissuing

curl https://tecrid.com/api/v1/routing/deliveries \
  -H "Authorization: Bearer $BRAND_ROUTING_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "tecrid": "TECRID·LAB-26-000001" }'

GET /api/v1/routing/deliveries · receive routed evidence

curl https://tecrid.com/api/v1/routing/deliveries \
  -H "Authorization: Bearer $RECIPIENT_TEC_API_KEY"

The recipient response contains only deliveries in which its organization is a party. Revocation blocks future delivery; it does not erase a package already received and relied upon.

08 / CERTIFICATION INTAKE

POST /api/v1/certification/submissions

A certification organization creates a program-scoped intake secret in its dashboard and gives it to an applicant's system. The endpoint resolves every TECRID, blocks samples and incomplete authority, freezes each accepted public record version, and returns one package fingerprint.

curl https://tecrid.com/api/v1/certification/submissions \
  -H "Authorization: Bearer $TECRID_INTAKE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "applicantOrganization": "Example Brand",
    "applicantName": "Quality Lead",
    "applicantEmail": "quality@example.com",
    "submissionReference": "CERT-2026-41",
    "tecrids": ["TECRID·LAB-26-000001"]
  }'

The token begins tec_intake_, is displayed once, and is stored by TECRID only as a SHA-256 hash. Passing the intake gate does not award certification.

08A / SHARE-CODE REDEMPTION

POST /api/v1/share-codes/redeem

A brand or supplier creates a one-time code addressed to one named certification body, retailer, or government workspace. The recipient redeems the code with its public organization code. The response is a frozen structured package plus a package fingerprint. A retry by the same named recipient returns the existing receipt rather than creating a second delivery.

curl https://tecrid.com/api/v1/share-codes/redeem   -H "Content-Type: application/json"   -d '{
    "code": "tec_share_••••••••••••",
    "recipientOrganizationCode": "HMTC"
  }'

Codes are high-entropy bearer credentials, recipient-bound, expiring, revocable before use, and consumed after the first successful redemption. Raw report files and onward sharing are excluded from the package.

09 / LEGACY REPORTS

POST /api/v1/legacy-reports

Upload an existing private PDF with multipart form data, its transcribed results JSON, the named laboratory, and the laboratory confirmation contact. The API returns a private intake id, source fingerprint, and confirmation path. Uploading never creates a TECRID by itself.

curl https://tecrid.com/api/v1/legacy-reports \
  -H "Authorization: Bearer $BRAND_TEC_API_KEY" \
  -F "document=@report.pdf;type=application/pdf" \
  -F "laboratoryName=Example Analytical" \
  -F "confirmationEmail=quality@example-lab.com" \
  -F "sampleName=Organic cacao powder" \
  -F 'results=[{"analyte":"Lead","resultText":"42","unit":"µg/kg"}]' \
  -F "attested=on"

10 / INSIGHTS

GET /api/v1/insights

Returns deterministic summaries across TECRIDs the organization issued or was authorized to receive: distinct records, result rows, SKU coverage, analyte counts, missing requested analytes, and the exact source TECRID behind every latest value. It does not infer safety, compliance, or comparability across units or methods.

11 / CONNECTOR PROFILES

Start with a report-release hook, not a LIMS replacement.

The TECRID Connect starter includes configuration profiles for LabWare, LabVantage, and STARLIMS plus generic JSON and CSV. These profiles map each system's release event and report-template fields to the same reserve/finalize protocol. They are implementation starters, not vendor-certified integrations.

Open the public TECRID Connect repository ↗

The repository is the canonical starting point for labs, brands, suppliers, retailers, and certification programs. It includes role-specific setup, report reservation and finalization examples, connector profiles, signing utilities, and deployment-safe environment guidance. A versioned ZIP remains available for offline review.

Download the current ZIP snapshot →

Outbound email is not yet a production claim. In-product notifications and controller receipts are live; email delivery still requires a configured sending provider and deliverability controls.

12 / ERRORS

Stable, inspectable responses.