Authentication and authorization
Use an out-of-band enrolled confidential backend with native AWS Cognito OAuth2 client_credentials. Obtain a short-lived access token from the operator-provided trusted Cognito token endpoint using HTTP Basic client authentication and grant_type=client_credentials, requesting the exact resource scope <API_RESOURCE_AUDIENCE>/access. Never place client secrets in browser code or this site. The API verifies trusted issuer/JWKS, RS256, expiry and time validity; token_use must be access, sub must equal client_id, and token lifetime is at most 300 seconds. Cognito M2M resource scope proves the configured API resource; it grants no Site or action permissions. Current active Allavus installation and explicit Site/action grants govern every request. ID tokens and user tokens are rejected. Provider enrollment and deployed activation remain separately gated. Human login migration is separate.
Receipt and recovery limits
Receipts support General Material COUNT only: positive integer quantity at most 1,000,000,000 in the canonical primary unit. Each new receipt needs a new Organization-unique lotCode across Sites/products. Separate deliveries need distinct sourceReceiptId and idempotency keys; recordedCost.sourceReference invoice evidence may be shared. Exact accepted retries return the original outcome; conflicting keys/source identities/lot codes return 409 without stock changes. Events and snapshots cover certified-receipts-only, never all stock writers or complete regulatory provenance.
Quickstart
After operator enrollment and activation, keep credentials in your backend secret store. Obtain an access token with the exact resource scope, then call the API with Authorization: Bearer. Download the Node client for executable request handling; supply your token at runtime.
curl --fail-with-body --header "Authorization: Bearer $ACCESS_TOKEN" 'https://machine-api.dev.allavus.com/v1/sites?limit=25'
GET /sites
Parameters
[
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
{
"name": "cursor",
"in": "query",
"schema": {
"type": "string",
"maxLength": 4096
}
}
]
Request
No request body
Responses and errors
{
"200": {
"description": "Curated result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SitePage"
}
}
}
},
"400": {
"description": "Invalid input",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"401": {
"description": "Bearer authentication required",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"404": {
"description": "Unavailable object or grant",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"409": {
"description": "Conflicting request or source identity",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"429": {
"description": "Finite local capacity exhausted",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"500": {
"description": "Internal error",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
}
Authorization
[
{
"bearerAuth": []
}
]
GET /sites/{siteId}/products
Parameters
[
{
"name": "siteId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
{
"name": "cursor",
"in": "query",
"schema": {
"type": "string",
"maxLength": 4096
}
}
]
Request
No request body
Responses and errors
{
"200": {
"description": "Curated result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProductPage"
}
}
}
},
"400": {
"description": "Invalid input",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"401": {
"description": "Bearer authentication required",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"404": {
"description": "Unavailable object or grant",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"409": {
"description": "Conflicting request or source identity",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"429": {
"description": "Finite local capacity exhausted",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"500": {
"description": "Internal error",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
}
Authorization
[
{
"bearerAuth": []
}
]
GET /sites/{siteId}/locations
Parameters
[
{
"name": "siteId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
{
"name": "cursor",
"in": "query",
"schema": {
"type": "string",
"maxLength": 4096
}
}
]
Request
No request body
Responses and errors
{
"200": {
"description": "Curated result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LocationPage"
}
}
}
},
"400": {
"description": "Invalid input",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"401": {
"description": "Bearer authentication required",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"404": {
"description": "Unavailable object or grant",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"409": {
"description": "Conflicting request or source identity",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"429": {
"description": "Finite local capacity exhausted",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"500": {
"description": "Internal error",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
}
Authorization
[
{
"bearerAuth": []
}
]
GET /sites/{siteId}/lots
Parameters
[
{
"name": "siteId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
{
"name": "cursor",
"in": "query",
"schema": {
"type": "string",
"maxLength": 4096
}
}
]
Request
No request body
Responses and errors
{
"200": {
"description": "Curated result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LotPage"
}
}
}
},
"400": {
"description": "Invalid input",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"401": {
"description": "Bearer authentication required",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"404": {
"description": "Unavailable object or grant",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"409": {
"description": "Conflicting request or source identity",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"429": {
"description": "Finite local capacity exhausted",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"500": {
"description": "Internal error",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
}
Authorization
[
{
"bearerAuth": []
}
]
GET /lots/{lotId}
Parameters
[
{
"name": "lotId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
]
Request
No request body
Responses and errors
{
"200": {
"description": "Curated result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Lot"
}
}
}
},
"400": {
"description": "Invalid input",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"401": {
"description": "Bearer authentication required",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"404": {
"description": "Unavailable object or grant",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"409": {
"description": "Conflicting request or source identity",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"429": {
"description": "Finite local capacity exhausted",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"500": {
"description": "Internal error",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
}
Authorization
[
{
"bearerAuth": []
}
]
GET /lots/{lotId}/lineage
Parameters
[
{
"name": "lotId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "depth",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 5
}
}
]
Request
No request body
Responses and errors
{
"200": {
"description": "Curated result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Lineage"
}
}
}
},
"400": {
"description": "Invalid input",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"401": {
"description": "Bearer authentication required",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"404": {
"description": "Unavailable object or grant",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"409": {
"description": "Conflicting request or source identity",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"429": {
"description": "Finite local capacity exhausted",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"500": {
"description": "Internal error",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
}
Authorization
[
{
"bearerAuth": []
}
]
POST /inventory-receipts
Parameters
[
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[\\x21-\\x7e]+$"
}
}
]
Request
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReceiptInput"
}
}
}
}
Responses and errors
{
"200": {
"description": "Curated result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReceiptOutcome"
}
}
}
},
"201": {
"description": "First acceptance",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReceiptOutcome"
}
}
}
},
"400": {
"description": "Invalid input",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"401": {
"description": "Bearer authentication required",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"404": {
"description": "Unavailable object or grant",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"409": {
"description": "Conflicting request or source identity",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"429": {
"description": "Finite local capacity exhausted",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"500": {
"description": "Internal error",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
}
Authorization
[
{
"bearerAuth": []
}
]
GET /inventory-receipts/{receiptId}
Parameters
[
{
"name": "receiptId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
]
Request
No request body
Responses and errors
{
"200": {
"description": "Curated result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReceiptOutcome"
}
}
}
},
"400": {
"description": "Invalid input",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"401": {
"description": "Bearer authentication required",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"404": {
"description": "Unavailable object or grant",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"409": {
"description": "Conflicting request or source identity",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"429": {
"description": "Finite local capacity exhausted",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"500": {
"description": "Internal error",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
}
Authorization
[
{
"bearerAuth": []
}
]
GET /events
Parameters
[
{
"name": "siteId",
"in": "query",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
{
"name": "cursor",
"in": "query",
"schema": {
"type": "string",
"maxLength": 4096
}
}
]
Request
No request body
Responses and errors
{
"200": {
"description": "Curated recovery result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EventsPage"
}
}
}
},
"400": {
"description": "Invalid input",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"401": {
"description": "Bearer authentication required",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"404": {
"description": "Unavailable object or grant",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"409": {
"description": "Conflicting request or source identity",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"429": {
"description": "Finite local capacity exhausted",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"500": {
"description": "Internal error",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
}
Authorization
[
{
"bearerAuth": []
}
]
POST /snapshots
Parameters
[]
Request
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"siteId": {
"type": "string",
"format": "uuid"
}
},
"required": [
"siteId"
]
}
}
}
}
Responses and errors
{
"201": {
"description": "Curated recovery result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SnapshotCreated"
}
}
}
},
"400": {
"description": "Invalid input",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"401": {
"description": "Bearer authentication required",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"404": {
"description": "Unavailable object or grant",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"409": {
"description": "Conflicting request or source identity",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"429": {
"description": "Finite local capacity exhausted",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"500": {
"description": "Internal error",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
}
Authorization
[
{
"bearerAuth": []
}
]
GET /snapshots/{snapshotId}
Parameters
[
{
"name": "snapshotId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "siteId",
"in": "query",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
{
"name": "cursor",
"in": "query",
"schema": {
"type": "string",
"maxLength": 4096
}
}
]
Request
No request body
Responses and errors
{
"200": {
"description": "Curated recovery result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SnapshotPage"
}
}
}
},
"400": {
"description": "Invalid input",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"401": {
"description": "Bearer authentication required",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"404": {
"description": "Unavailable object or grant",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"409": {
"description": "Conflicting request or source identity",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"429": {
"description": "Finite local capacity exhausted",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"500": {
"description": "Internal error",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
}
Authorization
[
{
"bearerAuth": []
}
]
GET /subscriptions
Parameters
[
{
"name": "siteId",
"in": "query",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
{
"name": "cursor",
"in": "query",
"schema": {
"type": "string",
"maxLength": 4096
}
}
]
Request
No request body
Responses and errors
{
"200": {
"description": "Curated recovery result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubscriptionsPage"
}
}
}
},
"400": {
"description": "Invalid input",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"401": {
"description": "Bearer authentication required",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"404": {
"description": "Unavailable object or grant",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"409": {
"description": "Conflicting request or source identity",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"429": {
"description": "Finite local capacity exhausted",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"500": {
"description": "Internal error",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
}
Authorization
[
{
"bearerAuth": []
}
]
POST /subscriptions
Parameters
[]
Request
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubscriptionCreate"
}
}
}
}
Responses and errors
{
"201": {
"description": "Curated recovery result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubscriptionCreated"
}
}
}
},
"400": {
"description": "Invalid input",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"401": {
"description": "Bearer authentication required",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"404": {
"description": "Unavailable object or grant",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"409": {
"description": "Conflicting request or source identity",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"429": {
"description": "Finite local capacity exhausted",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"500": {
"description": "Internal error",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
}
Authorization
[
{
"bearerAuth": []
}
]
PATCH /subscriptions/{subscriptionId}
Parameters
[
{
"name": "subscriptionId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
]
Request
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubscriptionPatch"
}
}
}
}
Responses and errors
{
"200": {
"description": "Curated recovery result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubscriptionUpdated"
}
}
}
},
"400": {
"description": "Invalid input",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"401": {
"description": "Bearer authentication required",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"404": {
"description": "Unavailable object or grant",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"409": {
"description": "Conflicting request or source identity",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"429": {
"description": "Finite local capacity exhausted",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"500": {
"description": "Internal error",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
}
Authorization
[
{
"bearerAuth": []
}
]
GET /subscriptions/{subscriptionId}/deliveries
Parameters
[
{
"name": "subscriptionId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "siteId",
"in": "query",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
{
"name": "cursor",
"in": "query",
"schema": {
"type": "string",
"maxLength": 4096
}
}
]
Request
No request body
Responses and errors
{
"200": {
"description": "Curated recovery result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeliveryHistory"
}
}
}
},
"400": {
"description": "Invalid input",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"401": {
"description": "Bearer authentication required",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"404": {
"description": "Unavailable object or grant",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"409": {
"description": "Conflicting request or source identity",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"429": {
"description": "Finite local capacity exhausted",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"500": {
"description": "Internal error",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
}
Authorization
[
{
"bearerAuth": []
}
]
POST /subscriptions/{subscriptionId}/replay
Parameters
[
{
"name": "subscriptionId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
]
Request
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReplayRequest"
}
}
}
}
Responses and errors
{
"200": {
"description": "Curated recovery result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReplayResult"
}
}
}
},
"400": {
"description": "Invalid input",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"401": {
"description": "Bearer authentication required",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"404": {
"description": "Unavailable object or grant",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"409": {
"description": "Conflicting request or source identity",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"429": {
"description": "Finite local capacity exhausted",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"500": {
"description": "Internal error",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
}
Authorization
[
{
"bearerAuth": []
}
]
Schemas and shared parameters
{
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT",
"description": "Trusted RS256 backend access token mapped to an active Allavus installation. Default JWT_AUDIENCE requires exact aud. Explicit COGNITO_CLIENT_CREDENTIALS requires token_use=access, sub=client_id, exact API resource scope and lifetime <=300 seconds; a present aud must match the API resource. Current Organization/Site/action grants remain mandatory."
}
},
"schemas": {
"Problem": {
"type": "object",
"additionalProperties": false,
"required": [
"type",
"title",
"status",
"requestId"
],
"properties": {
"type": {
"type": "string"
},
"title": {
"type": "string"
},
"status": {
"type": "integer"
},
"requestId": {
"type": "string",
"format": "uuid"
}
}
},
"Site": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
]
},
"Product": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"associationId": {
"type": "string",
"format": "uuid"
},
"masterId": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"primaryUnitId": {
"type": "string",
"format": "uuid"
},
"primaryUnitType": {
"type": "string"
}
},
"required": [
"id",
"associationId",
"masterId",
"name",
"primaryUnitId",
"primaryUnitType"
]
},
"Location": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"parentId": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "Active same-Site visible parent reference; null when absent or unavailable."
}
},
"required": [
"id",
"name",
"parentId"
]
},
"Lot": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"siteId": {
"type": "string",
"format": "uuid"
},
"productId": {
"type": "string",
"format": "uuid"
},
"quantity": {
"type": "string",
"pattern": "^[0-9]+(?:\\.[0-9]+)?$"
},
"unitId": {
"type": "string",
"format": "uuid",
"description": "Required unit from GLOBAL, current Organization or current Site namespace; invalid legacy references fail closed with 404."
},
"locationId": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "Active same-Site location visible under current action grants; null when absent or unavailable."
},
"expiryDate": {
"type": "string",
"format": "date-time",
"nullable": true
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"siteId",
"productId",
"quantity",
"unitId",
"locationId",
"expiryDate",
"updatedAt"
]
},
"ReceiptOutcome": {
"type": "object",
"additionalProperties": false,
"properties": {
"receiptId": {
"type": "string",
"format": "uuid"
},
"siteId": {
"type": "string",
"format": "uuid"
},
"lotId": {
"type": "string",
"format": "uuid"
},
"productId": {
"type": "string",
"format": "uuid"
},
"unitId": {
"type": "string",
"format": "uuid"
},
"quantity": {
"type": "string",
"pattern": "^[0-9]+(?:\\.[0-9]+)?$"
}
},
"required": [
"receiptId",
"siteId",
"lotId",
"productId",
"unitId",
"quantity"
]
},
"RecordedCost": {
"type": "object",
"additionalProperties": false,
"properties": {
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"sourceReference": {
"description": "Invoice or recorded cost evidence; may be reused by separate deliveries. Financial identity follows the accepted receipt command, not this reference.",
"type": "string",
"minLength": 1,
"maxLength": 128
},
"materials": {
"type": "string",
"pattern": "^\\d+(?:\\.\\d{1,18})?$",
"nullable": true
},
"packaging": {
"type": "string",
"pattern": "^\\d+(?:\\.\\d{1,18})?$",
"nullable": true
},
"labour": {
"type": "string",
"pattern": "^\\d+(?:\\.\\d{1,18})?$",
"nullable": true
},
"overhead": {
"type": "string",
"pattern": "^\\d+(?:\\.\\d{1,18})?$",
"nullable": true
},
"landedCosts": {
"type": "string",
"pattern": "^\\d+(?:\\.\\d{1,18})?$",
"nullable": true
}
},
"required": [
"currency",
"sourceReference"
]
},
"ReceiptInput": {
"type": "object",
"additionalProperties": false,
"properties": {
"siteId": {
"type": "string",
"format": "uuid"
},
"productId": {
"type": "string",
"format": "uuid"
},
"locationId": {
"type": "string",
"format": "uuid"
},
"unitId": {
"type": "string",
"format": "uuid"
},
"quantity": {
"type": "string",
"pattern": "^[1-9][0-9]{0,9}$",
"description": "Positive integer at most 1000000000; canonical primary unit only."
},
"lotCode": {
"description": "New Allavus physical identifier, unique among codes throughout the Organization, including other Sites/products. Not a reusable external supplier-lot reference; duplicate codes return 409.",
"type": "string",
"minLength": 1,
"maxLength": 128
},
"expiryDate": {
"type": "string",
"format": "date-time"
},
"supplierId": {
"type": "string",
"format": "uuid",
"nullable": true
},
"sourceNamespace": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"sourceReceiptId": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"recordedCost": {
"allOf": [
{
"$ref": "#/components/schemas/RecordedCost"
}
],
"nullable": true
}
},
"required": [
"siteId",
"productId",
"locationId",
"unitId",
"quantity",
"lotCode",
"expiryDate",
"sourceNamespace",
"sourceReceiptId"
]
},
"Lineage": {
"type": "object",
"additionalProperties": false,
"properties": {
"rootLotId": {
"type": "string",
"format": "uuid"
},
"nodes": {
"type": "array",
"maxItems": 100,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"format": "uuid"
}
},
"required": [
"id"
]
}
},
"edges": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"from": {
"type": "string",
"format": "uuid"
},
"to": {
"type": "string",
"format": "uuid"
},
"relationship": {
"type": "string",
"enum": [
"SOURCE_LOT",
"MOTHER_LOT"
]
}
},
"required": [
"from",
"to",
"relationship"
]
}
},
"truncated": {
"type": "boolean"
},
"completeness": {
"type": "string",
"enum": [
"LEGACY_INCOMPLETE"
]
},
"coverage": {
"type": "string"
}
},
"required": [
"rootLotId",
"nodes",
"edges",
"truncated",
"completeness",
"coverage"
]
},
"SitePage": {
"type": "object",
"additionalProperties": false,
"properties": {
"items": {
"type": "array",
"maxItems": 100,
"items": {
"$ref": "#/components/schemas/Site"
}
},
"nextCursor": {
"type": "string",
"nullable": true
},
"consistency": {
"type": "string",
"enum": [
"MUTABLE_LIST"
]
}
},
"required": [
"items",
"nextCursor",
"consistency"
]
},
"ProductPage": {
"type": "object",
"additionalProperties": false,
"properties": {
"items": {
"type": "array",
"maxItems": 100,
"items": {
"$ref": "#/components/schemas/Product"
}
},
"nextCursor": {
"type": "string",
"nullable": true
},
"consistency": {
"type": "string",
"enum": [
"MUTABLE_LIST"
]
}
},
"required": [
"items",
"nextCursor",
"consistency"
]
},
"LocationPage": {
"type": "object",
"additionalProperties": false,
"properties": {
"items": {
"type": "array",
"maxItems": 100,
"items": {
"$ref": "#/components/schemas/Location"
}
},
"nextCursor": {
"type": "string",
"nullable": true
},
"consistency": {
"type": "string",
"enum": [
"MUTABLE_LIST"
]
}
},
"required": [
"items",
"nextCursor",
"consistency"
]
},
"LotPage": {
"type": "object",
"additionalProperties": false,
"properties": {
"items": {
"type": "array",
"maxItems": 100,
"items": {
"$ref": "#/components/schemas/Lot"
}
},
"nextCursor": {
"type": "string",
"nullable": true
},
"consistency": {
"type": "string",
"enum": [
"MUTABLE_LIST"
]
}
},
"required": [
"items",
"nextCursor",
"consistency"
]
},
"ReceiptEvent": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"position": {
"type": "string",
"pattern": "^[0-9]+$"
},
"payload": {
"$ref": "#/components/schemas/ReceiptEventPayload"
},
"recordedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"position",
"payload",
"recordedAt"
]
},
"EventsPage": {
"type": "object",
"additionalProperties": false,
"properties": {
"items": {
"type": "array",
"maxItems": 100,
"items": {
"$ref": "#/components/schemas/ReceiptEvent"
}
},
"hasMore": {
"type": "boolean"
},
"cursor": {
"type": "string",
"maxLength": 4096
},
"coverage": {
"type": "string",
"enum": [
"certified-receipts-only"
]
},
"recovery": {
"type": "string"
}
},
"required": [
"items",
"hasMore",
"cursor",
"coverage",
"recovery"
]
},
"SnapshotCreated": {
"type": "object",
"additionalProperties": false,
"properties": {
"snapshotId": {
"type": "string",
"format": "uuid"
},
"expiresAt": {
"type": "string",
"format": "date-time"
},
"itemCount": {
"type": "integer",
"minimum": 0,
"maximum": 1000
},
"checkpoint": {
"type": "string",
"maxLength": 4096
},
"coverage": {
"type": "string",
"enum": [
"current-lots-and-certified-receipt-checkpoint"
]
}
},
"required": [
"snapshotId",
"expiresAt",
"itemCount",
"checkpoint",
"coverage"
]
},
"SnapshotPage": {
"type": "object",
"additionalProperties": false,
"properties": {
"snapshotId": {
"type": "string",
"format": "uuid"
},
"items": {
"type": "array",
"maxItems": 100,
"items": {
"$ref": "#/components/schemas/Lot"
}
},
"hasMore": {
"type": "boolean"
},
"cursor": {
"type": "string",
"maxLength": 4096,
"nullable": true
},
"checkpoint": {
"type": "string",
"maxLength": 4096
}
},
"required": [
"snapshotId",
"items",
"hasMore",
"cursor",
"checkpoint"
]
},
"Subscription": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"siteId": {
"type": "string",
"format": "uuid"
},
"callbackUrl": {
"type": "string",
"format": "uri",
"maxLength": 2048
},
"keyId": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,128}$"
},
"state": {
"type": "string",
"enum": [
"PENDING",
"ACTIVE",
"SUSPENDED"
]
},
"checkpoint": {
"type": "string",
"pattern": "^[0-9]+$"
},
"version": {
"type": "integer",
"minimum": 1
}
},
"required": [
"id",
"siteId",
"callbackUrl",
"keyId",
"state",
"checkpoint",
"version"
]
},
"SubscriptionsPage": {
"type": "object",
"additionalProperties": false,
"properties": {
"items": {
"type": "array",
"maxItems": 100,
"items": {
"$ref": "#/components/schemas/Subscription"
}
},
"cursor": {
"type": "string",
"maxLength": 4096,
"nullable": true
}
},
"required": [
"items",
"cursor"
]
},
"SubscriptionCreate": {
"type": "object",
"additionalProperties": false,
"properties": {
"siteId": {
"type": "string",
"format": "uuid"
},
"callbackUrl": {
"type": "string",
"format": "uri",
"maxLength": 2048,
"description": "Public HTTPS only, port443, no credentials/fragments, connection-time DNS/TLS checks."
},
"keyId": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,128}$"
}
},
"required": [
"siteId",
"callbackUrl",
"keyId"
]
},
"SubscriptionPatch": {
"type": "object",
"additionalProperties": false,
"properties": {
"siteId": {
"type": "string",
"format": "uuid"
},
"callbackUrl": {
"type": "string",
"format": "uri",
"maxLength": 2048,
"description": "Public HTTPS only, port443, no credentials/fragments, connection-time DNS/TLS checks."
},
"keyId": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,128}$"
},
"state": {
"type": "string",
"enum": [
"PENDING",
"SUSPENDED"
]
}
},
"required": [
"siteId"
]
},
"SubscriptionCreated": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"state": {
"type": "string",
"enum": [
"PENDING"
]
},
"ownershipVerification": {
"type": "string"
}
},
"required": [
"id",
"state",
"ownershipVerification"
]
},
"SubscriptionUpdated": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"state": {
"type": "string",
"enum": [
"PENDING",
"ACTIVE",
"SUSPENDED"
]
},
"version": {
"type": "integer"
}
},
"required": [
"id",
"state",
"version"
]
},
"DeliveryAttempt": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"deliveryId": {
"type": "string",
"format": "uuid"
},
"attempt": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
},
"errorCode": {
"type": "string",
"nullable": true
},
"recordedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"deliveryId",
"attempt",
"status",
"errorCode",
"recordedAt"
]
},
"DeliveryHistory": {
"type": "object",
"additionalProperties": false,
"properties": {
"items": {
"type": "array",
"maxItems": 100,
"items": {
"$ref": "#/components/schemas/DeliveryAttempt"
}
},
"cursor": {
"type": "string",
"maxLength": 4096,
"nullable": true
},
"listSemantics": {
"type": "string"
}
},
"required": [
"items",
"cursor",
"listSemantics"
]
},
"ReplayRequest": {
"type": "object",
"additionalProperties": false,
"properties": {
"siteId": {
"type": "string",
"format": "uuid"
},
"cursor": {
"type": "string",
"maxLength": 4096
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
"required": [
"siteId"
]
},
"ReplayResult": {
"type": "object",
"additionalProperties": false,
"properties": {
"queued": {
"type": "integer",
"minimum": 0,
"maximum": 100
},
"cursor": {
"type": "string",
"maxLength": 4096
},
"deliverySemantics": {
"type": "string"
}
},
"required": [
"queued",
"cursor",
"deliverySemantics"
]
},
"ReceiptEventPayload": {
"type": "object",
"additionalProperties": false,
"properties": {
"version": {
"type": "integer",
"enum": [
1
]
},
"type": {
"type": "string",
"enum": [
"receipt.recorded"
]
},
"eventId": {
"type": "string",
"format": "uuid"
},
"commandId": {
"type": "string",
"format": "uuid"
},
"lotId": {
"type": "string",
"format": "uuid"
},
"productId": {
"type": "string",
"format": "uuid"
},
"quantity": {
"type": "string"
},
"unitId": {
"type": "string",
"format": "uuid"
},
"siteId": {
"type": "string",
"format": "uuid"
},
"actor": {
"type": "object",
"additionalProperties": false,
"properties": {
"kind": {
"type": "string",
"enum": [
"USER",
"INTEGRATION"
]
},
"id": {
"type": "string",
"format": "uuid"
},
"subject": {
"type": "string"
}
},
"required": [
"kind",
"id",
"subject"
]
},
"source": {
"type": "object",
"additionalProperties": false,
"properties": {
"namespace": {
"type": "string"
},
"receiptId": {
"type": "string"
}
},
"required": [
"namespace",
"receiptId"
]
},
"eventTime": {
"type": "string",
"format": "date-time"
},
"recordedTime": {
"type": "string",
"format": "date-time"
},
"coverage": {
"type": "string",
"enum": [
"CERTIFIED_RECEIPTS_ONLY"
]
},
"historicalCompleteness": {
"type": "string",
"enum": [
"INCOMPLETE"
]
}
},
"required": [
"version",
"type",
"eventId",
"commandId",
"lotId",
"productId",
"quantity",
"unitId",
"siteId",
"actor",
"source",
"eventTime",
"recordedTime",
"coverage",
"historicalCompleteness"
]
},
"ReceiptWebhook": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"type": {
"type": "string",
"enum": [
"inventory.receipt.recorded"
]
},
"version": {
"type": "integer",
"enum": [
1
]
},
"payload": {
"$ref": "#/components/schemas/ReceiptEventPayload"
}
},
"required": [
"id",
"type",
"version",
"payload"
]
}
}
}
Paging, idempotency, errors and complete usage contract
Canonical source README follows as plain text. Deployment authentication profile above specializes its provider-neutral JWT description.
# Programmable API v1 — local source contract
This contract describes locally implemented source. The [dev AWS handoff](dev-aws.md) records native Cognito authentication, proposed API/reference hosts, local testing and gated Terraform/publication steps. Provider enrollment, ingress deployment, public activation, throughput targets and pilot acceptance remain separately gated. No real provider credentials or customer records are needed for verification.
Use an out-of-band enrolled confidential backend identity. The API verifies RS256 signatures against one configured trusted key source and requires a configured trusted issuer/resource, nonempty subject and expiry. The default `JWT_AUDIENCE` profile requires exact JWT `aud`. The explicit AWS `COGNITO_CLIENT_CREDENTIALS` profile validates `token_use=access`, `sub=client_id`, the exact configured resource scope and a maximum300-second lifetime; a present `aud` must still match the resource. Cognito M2M can omit `aud`; scope alone supplies no application grants. It resolves the identity to one current active, unexpired installation in one Organization. JWT claims do not grant tenant/Site access. Existing verified Organization owners administer pending enrollment, explicit activation, grants, rotation, suspension and terminal revocation. No client secrets are stored or returned by these endpoints.
Every request fetches current installation state; every command retains its installation lock through commit. Revocation waits for admitted commands, then blocks new admission. Already admitted reads can finish. Existing outcomes and business records remain retained. Grant changes invalidate old cursors. A valid bearer token is never sufficient to access an ungranted Site or another installation's outcome.
## Read and receipt contract
[openapi.json](./openapi.json) is the OpenAPI 3.0.3 contract. Responses contain only curated fields. Identifiers are UUID strings, quantities are decimal strings and times use RFC3339. Legacy stored stock uses floating point; serializing its current value as a string does not manufacture additional precision. New machine receipts currently admit positive integer quantity up to 1,000,000,000 in the General Material catalogue product's canonical primary unit; other quantities/groups/conversions fail explicitly. Unknown cost remains unknown; no zero cost is synthesized. Only explicit existing active Site leaf locations and same-Site active suppliers are accepted. Arbitrary document URLs are unsupported and rejected.
Products expose their Site catalogue association and stable catalogue master identity. `id` is the product identifier accepted by receipts; `associationId` and `masterId` serve different identities. Lots include their actual Site, canonical quantity/unit, location, expiry and last stored update timestamp. A lot ID never authorizes disclosure. Locations expose only ID, label and parent ID. Nullable location/parent IDs are returned only when the referenced active record is visible in the same Site; unavailable references are null, including location IDs hidden by current action grants. Required product/unit references must belong to the selected Site/effective GLOBAL, Organization or Site namespace. Invalid legacy required references make the lot/list/snapshot unavailable (404), rather than disclose foreign IDs. `/sites` returns active Sites covered by current installation grants, with no Organization discovery.
Lists default to 25 items, maximum 100. Follow opaque `nextCursor`; preserve the same path and limit. Cursors expire after 15 minutes and bind installation, tenant, grant version, operation/path, limit and position. They are authenticated and encrypted. Lists declare `MUTABLE_LIST`: concurrent edits can change later pages; they are not point-in-time exports. Retained snapshots, when enabled, use their separate checkpoint contract.
Lineage accepts depth 1–5 (default 5), at most 100 nodes and a finite query budget. It contains only same-Site source-lot/mother-lot links, suppresses inaccessible related identifiers and returns `LEGACY_INCOMPLETE`. `truncated` reports traversal limits; false does not mean complete cultivation or production provenance. This is not a global genealogy or full stock movement feed.
Submit receipts with `Idempotency-Key` (1–128 visible ASCII characters). The key is scoped to Organization, installation and receipt operation. A canonical validated request fingerprint includes Site and source identity. Exact retries return the original outcome with HTTP 200; first acceptance returns 201. Reusing a key for another request returns 409. Source namespace plus receipt identity is additionally unique across the Organization, including other installations; a reused source under a different key or installation returns 409 without disclosing the original result. Keep namespaces stable across reconnects and rotations. Reauthorize stored results using the current Site `receipts:write` grant. GET receipt outcomes requires the creating installation and current `receipts:write` grant.
The command's stock, canonical costing/evidence, certified receipt journal, outbox publication and durable outcome share one transaction. A failed command commits none of these. Retrying an accepted command creates no second lot. Receipt events cover certified receipt producers only; they do not certify all legacy stock writers.
`lotCode` is a new Allavus physical identifier, unique among identifier codes throughout the Organization, including other Sites and products. Separate deliveries require distinct Allavus lot codes and business `sourceReceiptId`/transport keys. Reusing a lot code for a new receipt returns 409 without stock, cost or trace changes; exact accepted retries still return the original outcome. The initial DTO has no separate external supplier-lot field or add-stock-to-existing-lot operation.
`recordedCost.sourceReference` preserves invoice or other recorded cost evidence and may repeat across valid separate deliveries. Machine financial identity follows the accepted receipt command while the invoice remains immutable detail evidence. Existing human financial-source semantics are unchanged.
Errors use allowlisted RFC9457-style problem fields `type`, `title`, `status`, `requestId`; `X-Request-Id` correlates support evidence. SQL, stack traces, tokens and internal data never enter response errors. Authentication fails 401, unavailable/ungranted objects 404, invalid input 400, conflicts 409 and exhausted local request budget 429. Responses use `Cache-Control: no-store`. An unknown field is invalid input, not a silently ignored option.
## Synthetic examples
Use only a task-owned disposable local runtime and its synthetic signed token. Do not source repository environment files. Replace the sample UUIDs with IDs from that runtime's curated read responses.
```sh
curl --fail-with-body --header "Authorization: Bearer $SYNTHETIC_ACCESS_TOKEN" \
'http://127.0.0.1:4000/v1/sites?limit=25'
curl --fail-with-body --header "Authorization: Bearer $SYNTHETIC_ACCESS_TOKEN" \
--header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-receipt-001' \
--data '{"siteId":"11000000-0000-4000-8000-000000000001","productId":"11000000-0000-4000-8000-000000000002","locationId":"11000000-0000-4000-8000-000000000003","unitId":"11000000-0000-4000-8000-000000000004","quantity":"3","lotCode":"Synthetic receipt","expiryDate":"2027-01-01T00:00:00Z","sourceNamespace":"synthetic-warehouse","sourceReceiptId":"delivery-001"}' \
'http://127.0.0.1:4000/v1/inventory-receipts'
```
`node docs/api/programmable-api/client.mjs --self-test` exercises the executable client against its synthetic loopback HTTP contract fixture. This client self-test is not authentication, database or deployment evidence. Full synthetic JWT/HTTP/runtime-role database verification belongs to the repository public-API harness.
Compatibility: v1 only adds fields that do not change documented meanings. Removal, renaming, widened disclosure, changed quantity semantics or stricter required inputs need an explicit version/deprecation decision and contract evidence. No activation date or deprecation deadline is promised here. Disable admission/producers to roll back; retain additive schema, accepted stock, audit, journal and outcomes, and drain only compatible consumers.
## Certified receipt recovery and callbacks
`GET /events` requires `siteId`, `events:read`, and optional bounded `limit`/opaque `cursor`. It returns `{items,hasMore,cursor,coverage,recovery}`. Event positions are decimal strings. Payloads are versioned certified receipt facts; coverage is `certified-receipts-only`. Expired/invalid cursors fail 400: create a fresh snapshot, enumerate it, then continue events from its checkpoint. Cursors remain installation/Site/grant/operation scoped.
`POST /snapshots` accepts only `{siteId}` and requires `snapshots:read`, `lots:read`, and `events:read`. It locks the Organization publication counter through finite lot capture, pairing committed current lot projections with a receipt checkpoint. It returns 201 `{snapshotId,expiresAt,itemCount,checkpoint,coverage}`. A snapshot retains at most 1,000 lots / 1MiB for 15 minutes; excess capture returns 409. `GET /snapshots/{snapshotId}?siteId=...` returns finite pages `{snapshotId,items,hasMore,cursor,checkpoint}`. Current creating-installation ownership, grant version, expiry and all three grants are rechecked on every page. Revoked/foreign/stale snapshots are unavailable. This checkpoint does not certify legacy writers outside the receipt producer matrix.
`GET /subscriptions?siteId=...` lists bounded current installation subscriptions. `POST /subscriptions` accepts only `{siteId,callbackUrl,keyId}`; it requires `subscriptions:manage` and `events:read`. It returns a PENDING subscription and no key material. HTTPS destinations must be public, port 443, without embedded credentials or fragments. Every actual attempt resolves and rejects unsafe answers, pins a checked address and preserves TLS hostname verification; redirects are rejected. Request/response sizes, DNS resolution and execution time are bounded. Signing keys are trusted operator inputs bound to the installation; missing or foreign ownership is rejected before signing or network access. Key provisioning and worker activation are out-of-band operator responsibilities.
The trusted worker sends a signed `{type:"subscription.challenge",nonce,subscriptionId}` request. The endpoint proves ownership with `x-allavus-challenge-response`, a hex HMAC-SHA256 of the nonce using the provisioned signing key. Successful signed challenge verification activates the subscription. No public operation can set ACTIVE. `PATCH /subscriptions/{subscriptionId}` accepts `{siteId,callbackUrl?,keyId?,state?:"PENDING"|"SUSPENDED"}`; changing destination/key returns to PENDING and requires fresh verification. Keep overlapping verification keys during an operator-managed rotation.
`GET /subscriptions/{subscriptionId}/deliveries?siteId=...` returns bounded append-only attempt history with allowlisted status/error codes. `POST /subscriptions/{subscriptionId}/replay` accepts `{siteId,cursor?,limit?}` (default25/max100), requires an ACTIVE subscription plus current `subscriptions:manage` and `events:read`, and queues only certified events in that Site. Replay can repeat delivery; retain receiver deduplication. It preserves lifetime attempt history and resets the bounded retry cycle only through this explicit operation.
Delivery body is `{id:eventId,type:"inventory.receipt.recorded",version:1,payload}`. Verify `x-allavus-signature` as `v1=` followed by hex HMAC-SHA256 over `timestamp + "." + deliveryId + "." + rawBody`, with the key selected by the provisioned `x-allavus-key-id`. Headers also include `x-allavus-delivery-id`, `x-allavus-event-id` and `x-allavus-timestamp` (seconds). Authenticate exact raw bytes, enforce a reasonable timestamp replay window, and deduplicate stable event IDs before applying effects. Delivery is at least once, never exactly once. Eight failed/redirected attempts exhaust the retry cycle into DEAD; explicit replay can requeue it while preserving evidence. Current installation/grants are checked before every job and network admission. Revocation waits for admitted sends, but an already transmitted HTTP request cannot be recalled.