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. 
{ "id": "org",    "displayName": "Organization", "attributionKeys": ["orgId"] }
{ "id": "team",   "displayName": "Team",         "attributionKeys": ["teamId"] }
{ "id": "model",  "displayName": "AI model",     "attributionKeys": ["modelId"] }
{ "id": "region", "displayName": "Region",       "attributionKeys": ["regionId"] }
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. 
{ "id": "org-acme",     "typeRefId": "org",   "metadata": { "plan": "enterprise" } }
{ "id": "team-eng",     "typeRefId": "team",  "metadata": {} }
{ "id": "user-alice",   "typeRefId": "user",  "metadata": {} }
{ "id": "agent-claude", "typeRefId": "agent", "metadata": {} }
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.

​
Capabilities

A capability is a metered resource that you allow customers to consume — for example api-calls, tokens, or seats. Capabilities form the column axis of the governance matrix. In V1 all capabilities are of type METER (a counter that increments on ingest and resets on cadence rollover). 
{ "id": "api-calls", "type": "METER" }
{ "id": "ai-tokens", "type": "METER" }

​
Assignments

An assignment is the per-(entity, capability) governance rule: how much of a capability 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, capabilityId, scopeEntityIds). 
{
  "entityId":    "team-eng",
  "capabilityId": "ai-tokens",
  "usageLimit":  50000,
  "cadence":     "P1M"
}
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.
CadenceResets every
PT1H1 hour
P1D1 day
P7D7 days
P30D30 days
P1M1 calendar month
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. 
// Node-wide budget — always applies
{ "entityId": "team-eng", "capabilityId": "ai-tokens", "scopeEntityIds": [],            "usageLimit": 50000, "cadence": "P1M" }

// Scoped sub-budget — only applies when model-gpt4o is in the resolved set
{ "entityId": "team-eng", "capabilityId": "ai-tokens", "scopeEntityIds": ["model-gpt4o"], "usageLimit": 5000,  "cadence": "P1M" }

​
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. 
org-acme
  └── team-eng
        ├── user-alice
        └── agent-claude
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 for a capability, the check endpoint returns hasAccess: true with an empty checks 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 endpoints:
  • Check (POST /owners/:ownerId/check) — read-only; returns hasAccess and current usage. Call this before allowing consumption.
  • Ingest (POST /owners/:ownerId/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.