Entity types
Entity types are vendor-defined categories of resource that can be governed. You define them once per environment — they describe the shape of your governance model, not specific instances of it. Entity types fall into two roles:- Hierarchical — levels in your customers’ org structure, such as
department,team,user, oragent. Entities of these types can be arranged in a parent–child tree so that consuming against a team also counts against its parent department. - Dimensional — cross-cutting attributes such as
region,model, orproduct. These are not placed in a hierarchy but can be used as scope filters on entity entitlements (see Scope).
attributionKeys field tells the governance engine which keys in a usage event’s dimensions map correspond to instances of this type. When an event carries { "departmentId": "engineering", "modelId": "gpt-4o" }, the engine resolves entity engineering of type department and entity gpt-4o of type model. The dimensions field in check and ingest requests is simply how you pass these attribution key–value pairs when you don’t know the entity IDs directly.
An entity type with no active entities can be archived. Upsert it again to restore it.
Entities
An entity is a specific instance of an entity type, owned by one of your Stigg customers. Each entity belongs to exactly one customer and has a uniqueid within that customer.
Entity entitlements
An entity entitlement is the per-(entity, feature/credit) governance rule: how much of a metered feature or credit an entity is allowed to consume per cadence period. Entity entitlements appear as entitlement columns in the Stigg console’s Governance tab. An entity entitlement governs either a feature (featureId) or a credit currency (currencyId), never both. Its natural key is (entityId, featureId or currencyId, scopeEntityIds).
Cadence
The cadence is an ISO 8601 duration that controls how often the usage counter resets. It takes a single unit:P<n>Y, P<n>M, P<n>W or P<n>D for years, months, weeks or days, and PT<n>H, PT<n>M or PT<n>S for hours, minutes or seconds. Combined durations such as P1M15D aren’t supported.
Periods start when the entity entitlement is created, not on the calendar: a
P1M budget created on May 12 resets on the 12th of each month.
A short cadence (e.g., PT1H) acts as a rate-limit window.
Scope (dimension-scoped sub-budgets)
An entity entitlement’sscopeEntityIds field lets you attach a tighter budget that applies only when a specific sub-context is present. For example, you might give platform a global budget of 200,000 tokens per month, and a tighter budget of 10,000 tokens that applies only when the gpt-4o entity is in the request’s resolved set.
Hierarchy
Entities can be arranged in a parent–child tree to reflect a customer’s organizational structure. TheparentId field on an entity entitlement places the entity in the hierarchy. An entity has one parent, shared by all its entity entitlements.
Governance is opt-in
If an entity has no entitlement, the check endpoint answers from the customer’s entitlement alone and omitschains. Governance only adds limits where you set them. You can roll out governance incrementally, and ungoverned entities continue to work exactly as before.
Check and Ingest
Governance exposes two runtime operations — see Check and Ingest for the full reference.- Check — read-only; returns
isGrantedand current usage. Call this before allowing consumption. - Ingest — increments the usage counter. Call this after consumption, once Check has allowed it.
Limits
Entities move one at a time. An entity can move to another parent, or detach from its parent, once it has no child entities. To reorganize a branch, work from the bottom up. When placing a new subtree, place each parent before its children, or in the same request.
For API rate limits, see Rate limits.
On the roadmap
The following are on the governance roadmap. Contact us to learn more.Allocated budgets per entity
By default, each entity has its own limit. With allocated budgets, a parent entity hands part of its budget down to its children. For example, a department with 1,000,000 tokens allocates 200,000 toplatform. Usage against the child’s allocation draws down the parent’s remaining pool automatically.