Skip to main content

​
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 org, team, user, or agent. Entities of these types can be arranged in a parent–child tree so that consuming against a team also counts against its parent org.
  • Dimensional — cross-cutting attributes such as region, model, or product. These are not placed in a hierarchy but can be used as scope filters on assignments (see Scope).
Both roles use the same underlying entity type object. The difference is only how the type is used: in a hierarchy, or as a scoping axis on an assignment.
The 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 { "orgId": "acme", "modelId": "gpt-4o" }, the engine resolves entity acme of type org 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.

​
Entities

An entity is a specific instance of an entity type, owned by one of your customers (the owner). Each entity belongs to exactly one owner and has a unique id within that owner’s scope.
Entities are the rows that assignments and usage counters bind to. You provision them from your backend whenever a customer creates an org, team, user, or AI agent in your product.

​
Assignments

An assignment 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. Assignments are the governance equivalent of entitlements — they appear as entitlement columns in the Stigg console’s Governance tab. The natural key is (entityId, featureId, scopeEntityIds).
Assignments are typically created by your customers through an in-app interface you build, though you can also set them programmatically on their behalf.

​
Cadence

The cadence is an ISO 8601 duration that controls how often the usage counter resets. A short cadence (e.g., PT1H) acts as a rate-limit window.

​
Scope (dimension-scoped sub-budgets)

An assignment’s scopeEntityIds field lets you attach a tighter budget that applies only when a specific sub-context is present. For example, you might give team-eng a global budget of 50,000 tokens per month, and a tighter budget of 5,000 tokens that applies only when the model-gpt4o 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. The parentId field on an assignment places the entity in the hierarchy.
The check endpoint evaluates the entire chain from the target entity up to the root. A request is granted only when every budget in the chain allows it.

​
Governance is opt-in

If an entity has no assignment, the check endpoint returns isGranted: true with an empty chains array. There is no default deny. You can roll out governance incrementally — 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 isGranted and current usage. Call this before allowing consumption.
  • Ingest — increments the usage counter. Call this after consumption. Ingest never gates — it always succeeds.
The typical pattern is: check → allow or deny → ingest (only on allow).

​
Coming in early access

The following capabilities are on the governance roadmap and available in early access. Contact us to learn more.

​
Allocated budgets per entity

Today, a limit is set directly on an entity. Allocated budgets let a parent entity distribute a portion of its own budget down to children — for example, an org allocates 200,000 tokens to team-eng out of its own 1,000,000 total. Consuming against the child’s allocation reduces the parent’s remaining pool automatically.

​
Soft limits

Hard limits block consumption when the limit is reached. Soft limits allow consumption to continue past the threshold but trigger a warning — giving your customers visibility and the chance to act before being cut off. Useful for grace periods and overage-aware pricing.

​
Alerts

Notify your customers (or your own systems) when an entity approaches or reaches its limit. Alerts will be configurable per threshold (e.g. 80%, 100%) and delivered via webhook or in-app notification.