Setting up governance

This guide covers the catalog setup you make as the vendor — both from the Stigg console and via the Stigg REST API. Most of these are one-time or infrequent operations; the Check and Ingest calls happen per-request at runtime.

Via the Stigg console

Define entity types

In the Stigg app, go to Governance → Entity types. The list shows all entity types defined for the environment, along with their attribution keys and the last time each was updated.

Click + New entity type to open the creation drawer.

New entity type — empty — New entity type drawer

Fill in:

Display name — a human-readable label (e.g. Organization). The entity type ID is auto-generated from it and can be edited.
Attribution keys — the dimension keys your usage events carry to identify instances of this type (e.g. orgId). Type a key and press Enter to add it; multiple keys are supported.

New entity type — ready to create — Attribution key added — ready to create

Once created, the new type appears in the list. Hover a row and click the ⋮ menu to Edit it.

Entity type created — Newly created entity type with edit option

View and manage entities for a customer

To view governance data for a specific customer:

Go to Customers → Customer accounts and open the customer record.

Click the Governance tab.

The tab shows the customer’s entity hierarchy on the left, their entity types in the Type column, and — for each entitlement — the current usage vs. limit broken out by scope (Node-wide and per-model or other dimension).

Customer Governance tab overview — Customer Governance tab — entity hierarchy with usage

Sort and prioritize entities

Use the Order by control (the sliders icon next to the type filter) to rank entities by consumption. Two modes are available:

Usage — ranks by absolute consumption, so the heaviest consumers appear first
Utilization — ranks by percentage of limit used, so entities closest to being blocked surface first

Sort order panel — Order by — Usage vs. Utilization

Switching to Utilization is the fastest way to spot entities that are about to hit their limit and may need a budget increase or intervention before they get blocked.

Add an entity to a customer

Click + Add entity to open the drawer.

Add entity — empty — Add entity drawer — empty

Fill in:

Entity ID — the unique identifier used in API calls (e.g. org-acme)
Entity type — select from the entity types defined for this environment

Add entity — entity type dropdown — Selecting an entity type

Parent entity (optional) — place this entity under a parent in the hierarchy (e.g. nest a user under a team)

Add entity — parent selected — Selecting a parent entity

Cardinality (optional) — restrict this entity’s budget to a specific sub-context by selecting entities to slice by

Add entity — cardinality dropdown — Cardinality — selecting entities to slice by

After adding entities, the full hierarchy is visible in the Governance tab with all entitlement columns.

Full governance hierarchy with all entities and entitlement columns

Edit an entitlement value inline

Click any entitlement cell in the Governance tab to edit the limit value inline, then confirm with the checkmark.

Inline edit entitlement — Inline editing an entitlement value

Via the SDK

Install the Stigg TypeScript client and initialize it with your server-side API key:

npm install @stigg/typescript

import Stigg from '@stigg/typescript';

const client = new Stigg({
  apiKey: process.env.STIGG_API_KEY,
});

All examples in the governance docs use this client instance.

Via the REST API

All governance operations use the Stigg REST API. Authenticate with your server-side API key:

X-API-KEY: <SERVER_API_KEY>

Step 1 — Define entity types

Entity types are the categories of resource you want to govern (e.g., org, team, user, agent). Define them once per environment. The attributionKeys are the dimension keys your ingest events carry to identify instances of each type.

const response = await client.v1Beta.entityTypes.upsert({
  types: [
    { id: 'org',   displayName: 'Organization', attributionKeys: ['orgId'] },
    { id: 'team',  displayName: 'Team',         attributionKeys: ['teamId'] },
    { id: 'user',  displayName: 'User',         attributionKeys: ['userId'] },
    { id: 'agent', displayName: 'AI agent',     attributionKeys: ['agentId'] },
  ],
});

curl -X PUT https://api.stigg.io/api/v1-beta/entity-types \
  -H "X-API-KEY: <SERVER_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "types": [
      { "id": "org",   "displayName": "Organization", "attributionKeys": ["orgId"] },
      { "id": "team",  "displayName": "Team",         "attributionKeys": ["teamId"] },
      { "id": "user",  "displayName": "User",         "attributionKeys": ["userId"] },
      { "id": "agent", "displayName": "AI agent",     "attributionKeys": ["agentId"] }
    ]
  }'

The upsert is idempotent — re-submitting the same payload is safe. Up to 100 types per request. Response (200 OK):

[
  {
    "id": "org",
    "displayName": "Organization",
    "attributionKeys": ["orgId"],
    "createdAt": "2026-01-15T10:00:00.000Z",
    "updatedAt": "2026-01-15T10:00:00.000Z"
  }
]

Listing entity types

for await (const entityType of client.v1Beta.entityTypes.list()) {
  console.log(entityType.id, entityType.displayName);
}

curl "https://api.stigg.io/api/v1-beta/entity-types" \
  -H "X-API-KEY: <SERVER_API_KEY>"

Step 2 — Provision entities per customer

When a customer creates an org, team, or user in your product, provision the corresponding entity in governance. The ownerId is the customer’s ID in your system.

const response = await client.v1Beta.customers.entities.upsert('cus-acme', {
  entities: [
    { id: 'org-acme',     entityTypeId: 'org',   metadata: { plan: 'enterprise' } },
    { id: 'team-eng',     entityTypeId: 'team' },
    { id: 'team-product', entityTypeId: 'team' },
    { id: 'agent-claude', entityTypeId: 'agent' },
  ],
});

curl -X PUT https://api.stigg.io/api/v1-beta/customers/cus-acme/entities \
  -H "X-API-KEY: <SERVER_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "entities": [
      { "id": "org-acme",     "entityTypeId": "org",   "metadata": { "plan": "enterprise" } },
      { "id": "team-eng",     "entityTypeId": "team" },
      { "id": "team-product", "entityTypeId": "team" },
      { "id": "agent-claude", "entityTypeId": "agent" }
    ]
  }'

Up to 100 entities per request. Idempotent — safe to re-run during re-syncs. Metadata patch semantics: keys present in metadata are merged over existing values. Set a key to "" to delete it. Omitting metadata entirely leaves the stored metadata unchanged. Response (200 OK):

[
  {
    "id": "org-acme",
    "entityTypeId": "org",
    "metadata": { "plan": "enterprise" },
    "archivedAt": null,
    "createdAt": "2026-01-15T10:00:00.000Z",
    "updatedAt": "2026-01-15T10:00:00.000Z"
  }
]

Listing entities

// All active entities for the customer
for await (const entity of client.v1Beta.customers.entities.list('cus-acme')) {
  console.log(entity.id, entity.entityTypeId);
}

// Filter by entity type
for await (const team of client.v1Beta.customers.entities.list('cus-acme', { entityTypeId: 'team' })) {
  console.log(team.id);
}

# All active entities
curl "https://api.stigg.io/api/v1-beta/customers/cus-acme/entities" \
  -H "X-API-KEY: <SERVER_API_KEY>"

Getting a single entity

const response = await client.v1Beta.customers.entities.retrieve('org-acme', { id: 'cus-acme' });

curl "https://api.stigg.io/api/v1-beta/customers/cus-acme/entities/org-acme" \
  -H "X-API-KEY: <SERVER_API_KEY>"

Archiving and unarchiving entities

Archiving is a soft-delete: the entity disappears from the list but remains accessible via GET-by-ID.

// Archive
await client.v1Beta.customers.entities.archive('cus-acme', { ids: ['team-old-project'] });

// Unarchive
await client.v1Beta.customers.entities.unarchive('cus-acme', { ids: ['team-old-project'] });

# Archive
curl -X POST https://api.stigg.io/api/v1-beta/customers/cus-acme/entities/archive \
  -H "X-API-KEY: <SERVER_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["team-old-project"] }'

Both return 204 No Content.

Step 3 — Create assignments

Assignments set the usage limit for an (entity, feature/credit) pair — they are the governance equivalent of entitlements, and appear as entitlement columns in the Stigg console’s Governance tab. They are typically created by your customers through an in-app interface, but you can also set them programmatically.

const response = await client.v1Beta.customers.assignments.upsert('cus-acme', {
  assignments: [
    { entityId: 'org-acme', featureId: 'feature-ai-tokens', usageLimit: 1_000_000, cadence: 'P1M' },
    { entityId: 'team-eng', featureId: 'feature-ai-tokens', parentId: 'org-acme', usageLimit: 200_000, cadence: 'P1M' },
  ],
});

curl -X PUT https://api.stigg.io/api/v1-beta/customers/cus-acme/assignments \
  -H "X-API-KEY: <SERVER_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "assignments": [
      { "entityId": "org-acme", "featureId": "feature-ai-tokens", "usageLimit": 1000000, "cadence": "P1M" },
      { "entityId": "team-eng", "featureId": "feature-ai-tokens", "parentId": "org-acme", "usageLimit": 200000, "cadence": "P1M" }
    ]
  }'

Patch semantics: on re-upsert, omitting usageLimit or cadence preserves the existing value. On first create, both are required. usageLimit: null — tracked but unlimited: setting usageLimit to null means usage is still counted and appears in check responses, but the limit never blocks. Useful for observability before enforcing. Response (200 OK):

[
  {
    "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "entityId": "org-acme",
    "featureId": "feature-ai-tokens",
    "scopeEntityIds": [],
    "usageLimit": 1000000,
    "cadence": "P1M",
    "parentId": null,
    "createdAt": "2026-01-15T10:00:00.000Z",
    "updatedAt": "2026-01-15T10:00:00.000Z"
  }
]

Hierarchy — placing entities in a tree

The parentId field places an entity under a parent in the governance hierarchy. The check endpoint evaluates every budget in the chain from the target entity to the root — a request is only granted when all budgets along the path allow it.

parentId is tri-state: omitting it leaves the current parent unchanged (new nodes default to root); null detaches the entity to root; an entity ID sets or changes the parent. Reparenting is only allowed for leaf nodes — a node with children cannot be moved.

Dimension-scoped sub-budgets

Add a tighter budget for a specific context by setting scopeEntityIds. The scoped budget applies only when every listed entity is present in the resolved set for the request.

await client.v1Beta.customers.assignments.upsert('cus-acme', {
  assignments: [
    // Node-wide budget — always applies
    { entityId: 'team-eng', featureId: 'feature-ai-tokens', scopeEntityIds: [],              usageLimit: 200_000, cadence: 'P1M' },
    // Tighter budget — applies only when model-gpt4o is in the request context
    { entityId: 'team-eng', featureId: 'feature-ai-tokens', scopeEntityIds: ['model-gpt4o'], usageLimit: 10_000,  cadence: 'P1M' },
  ],
});

Listing assignments

// All assignments for the customer
for await (const assignment of client.v1Beta.customers.assignments.list('cus-acme')) {
  console.log(assignment.entityId, assignment.featureId, assignment.usageLimit);
}

// Filter by entity
for await (const assignment of client.v1Beta.customers.assignments.list('cus-acme', { entityId: 'team-eng' })) {
  console.log(assignment);
}

curl "https://api.stigg.io/api/v1-beta/customers/cus-acme/assignments?entityId=team-eng" \
  -H "X-API-KEY: <SERVER_API_KEY>"

Getting started

Developer tools

Governance (Private Beta)

Modeling your pricing in Stigg

Managing customers, subscriptions and entitlements

Getting usage data into Stigg

Snap-in widgets

Native integrations

Importing and exporting data

Going live

Workflow automation

Rolling out pricing changes with confidence

Price localization

Managing your account

High-availability and scale

Security & compliance

Via the Stigg console

Define entity types

View and manage entities for a customer

Sort and prioritize entities

Add an entity to a customer

Edit an entitlement value inline

Via the SDK

Via the REST API

Step 1 — Define entity types

Listing entity types

Step 2 — Provision entities per customer

Listing entities

Getting a single entity

Archiving and unarchiving entities

Step 3 — Create assignments

Hierarchy — placing entities in a tree

Dimension-scoped sub-budgets

Listing assignments

What’s next

Check and ingest

Query the governance tree

​Via the Stigg console

​Define entity types

​View and manage entities for a customer

​Sort and prioritize entities

​Add an entity to a customer

​Edit an entitlement value inline

​Via the SDK

​Via the REST API

​Step 1 — Define entity types

​Listing entity types

​Step 2 — Provision entities per customer

​Listing entities

​Getting a single entity

​Archiving and unarchiving entities

​Step 3 — Create assignments

​Hierarchy — placing entities in a tree

​Dimension-scoped sub-budgets

​Listing assignments

​What’s next

Check and ingest

Query the governance tree

Via the Stigg console

Define entity types

View and manage entities for a customer

Sort and prioritize entities

Add an entity to a customer

Edit an entitlement value inline

Via the SDK

Via the REST API

Step 1 — Define entity types

Listing entity types

Step 2 — Provision entities per customer

Listing entities

Getting a single entity

Archiving and unarchiving entities

Step 3 — Create assignments

Hierarchy — placing entities in a tree

Dimension-scoped sub-budgets

Listing assignments

What’s next