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 department, 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 department.
  • 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 entity entitlements (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 entity entitlement.
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 { "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 unique id within that customer.
Entities are the rows that entity entitlements and usage counters bind to. You provision them from your backend whenever a customer creates a department, team, user, or AI agent in your product.

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).
Entity entitlements 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. 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’s scopeEntityIds 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. The parentId field on an entity entitlement places the entity in the hierarchy. An entity has one parent, shared by all its entity entitlements.
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 entitlement, the check endpoint answers from the customer’s entitlement alone and omits chains. 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 isGranted and current usage. Call this before allowing consumption.
  • Ingest — increments the usage counter. Call this after consumption, once Check has allowed it.
The typical pattern is: check → allow or deny → ingest (only on allow).

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 to platform. Usage against the child’s allocation draws down the parent’s remaining pool automatically.

Soft limits

Hard limits block consumption when the limit is reached. Soft limits let consumption continue past the threshold and trigger a warning, so your customers can act before anything gets cut off. They suit grace periods and overage-aware pricing.