Reference
API Reference
The MintPass API implements the protocol specification as a REST interface. All endpoints accept and return JSON. Entitlement state is always consistent with the ledger.
Containers
A container is the root object that holds entitlements for an actor. Query a container to get the full entitlement state in a single call.
GET
/containers/{container_id}/state
{
"container": "user_8821",
"entitlements": [{ ... }],
"ledger_events": 4,
"last_mutation": "2026-03-13T12:45:00Z"
}
"container": "user_8821",
"entitlements": [{ ... }],
"ledger_events": 4,
"last_mutation": "2026-03-13T12:45:00Z"
}
Entitlements
Entitlements are the core protocol objects. Each entitlement has a lifecycle state, an authority, and an optional capacity. State transitions are controlled by the Guardian.
POST
/entitlements/issue
Issuance
{
"container": "user_8821",
"entitlement": {
"type": "access",
"resource": "premium_content",
"authority": "issuer",
"capacity": 1
},
"issued_at": "2026-03-13T12:45:00Z"
}
"container": "user_8821",
"entitlement": {
"type": "access",
"resource": "premium_content",
"authority": "issuer",
"capacity": 1
},
"issued_at": "2026-03-13T12:45:00Z"
}
GET
/entitlements/{entitlement_id}
POST
/entitlements/{entitlement_id}/transition
Mutation
POST
/entitlements/{entitlement_id}/revoke
Ledger Events
Every state mutation produces an immutable ledger event. The ledger is append-only. Entitlement history is always reconstructable from the event sequence.
GET
/entitlements/{entitlement_id}/ledger
{
"events": [
{
"type": "issued",
"at": "2026-03-13T12:45:00Z",
"by": "auth_root",
"state_after": "issued"
}
]
}
"events": [
{
"type": "issued",
"at": "2026-03-13T12:45:00Z",
"by": "auth_root",
"state_after": "issued"
}
]
}
GET
/containers/{container_id}/ledger
Full Reference
Full API documentation — coming soon