Skip to main content
Governance exposes two runtime operations: Check and Ingest.
  • Check reads the current usage and returns a gate decision. It never modifies state.
  • Ingest records a consumption event and increments the usage counter. It never gates.
The typical pattern is: check → allow or deny based on isGranted → ingest (only if allowed).
Governance is opt-in. If an entity has no entitlement for the requested feature or currency, Check answers from the customer’s entitlement alone and omits chains. Governance only adds limits where you set them.
The Sidecar answers Check from its cache when it uses Redis, kept current by the persistent cache service. Support without Redis is coming soon.
Dimensions that match no entity are ignored. A typo in an entity ID, an entity you haven’t provisioned yet, or a key that isn’t an attribution key gets a customer-level answer with no chains, and its usage counts only for the customer. Validate entity IDs before you send them, and treat a missing chains as “not governed”.
If you haven’t initialized the client yet, see Setting up governance.

Check

GET /api/v1/customers/:id/entitlements/check Returns whether the requested amount of a feature or credit is permitted, along with current usage and the applicable limit. Call this before allowing consumption.

By feature

Pass the feature ID and dimensions that identify the governed entities. The governance engine resolves the entity hierarchy from the dimensions automatically.

By credit

Use currencyId instead of featureId to check against a credit balance limit.
Pass either featureId or currencyId, not both.

Check request fields

Check response

200 OK:

Finding the binding constraint

A governance denial has the same accessDeniedReason as a customer-level overage, RequestedUsageExceedingLimit. To tell them apart, look for the node in chains with isGranted: false: that’s the budget that denied the request. One exception: for a feature that consumes credits, a budget on that credit currency denies with InsufficientCredits, and its node isn’t in chains.

Ingest

Records consumption and increments the usage counter. Ingest never gates — call Check first if you need a permit decision before consuming. Use reportUsage for synchronous, real-time enforcement — credit-backed features return an updated balance in the response immediately. Use reportEvent for high-volume, eventually-consistent metering (≈10 s latency) where a real-time balance is not required.

reportUsage

Response (201 Created): entities lists the updated usage of every entity entitlement the report counted towards, from the attributed entity up to the root, with featureId or currencyId. It’s omitted when the report counted towards no entity entitlement. For credit-backed features, the response also has a credits array with each wallet’s balance.

reportEvent

reportEvent counts towards a feature only through a meter: a feature with an event meter that matches eventName and aggregates a dimension, here tokenCount. Without one, the event is accepted but counts nothing. The example assumes such a meter.

Batching usage reports

Both reportUsage and reportEvent accept up to 100 records per request.

Ingest fields


Full check-then-ingest pattern