> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stigg.io/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](/api-and-sdks/api-reference/rest/overview). Most of these are one-time or infrequent operations; the [Check and Ingest](/documentation/governance/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.
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.
Once created, the new type appears in the list. Hover a row and click the **⋮** menu to **Edit** it.
### View and manage entities for a customer
To view governance data for a specific customer:
1. Go to **Customers → Customer accounts** and open the customer record.
2. 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).
### 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
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.
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
* **Parent entity** *(optional)* — place this entity under a parent in the hierarchy (e.g. nest a user under a team)
* **Cardinality** *(optional)* — restrict this entity's budget to a specific sub-context by selecting entities to slice by
After adding entities, the full hierarchy is visible in the Governance tab with all 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.
***
## Via the SDK
Install the Stigg TypeScript client and initialize it with your server-side API key:
```bash theme={null}
npm install @stigg/typescript
```
```typescript theme={null}
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](/api-and-sdks/api-reference/rest/overview). Authenticate with your server-side API key:
```bash theme={null}
X-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.
```typescript TypeScript theme={null}
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'] },
],
});
```
```bash curl theme={null}
curl -X PUT https://api.stigg.io/api/v1-beta/entity-types \
-H "X-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`):
```json theme={null}
[
{
"id": "org",
"displayName": "Organization",
"attributionKeys": ["orgId"],
"createdAt": "2026-01-15T10:00:00.000Z",
"updatedAt": "2026-01-15T10:00:00.000Z"
}
]
```
### Listing entity types
```typescript TypeScript theme={null}
for await (const entityType of client.v1Beta.entityTypes.list()) {
console.log(entityType.id, entityType.displayName);
}
```
```bash curl theme={null}
curl "https://api.stigg.io/api/v1-beta/entity-types" \
-H "X-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.
```typescript TypeScript theme={null}
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' },
],
});
```
```bash curl theme={null}
curl -X PUT https://api.stigg.io/api/v1-beta/customers/cus-acme/entities \
-H "X-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`):
```json theme={null}
[
{
"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
```typescript TypeScript theme={null}
// 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);
}
```
```bash curl theme={null}
# All active entities
curl "https://api.stigg.io/api/v1-beta/customers/cus-acme/entities" \
-H "X-API-KEY: "
```
### Getting a single entity
```typescript TypeScript theme={null}
const response = await client.v1Beta.customers.entities.retrieve('org-acme', { id: 'cus-acme' });
```
```bash curl theme={null}
curl "https://api.stigg.io/api/v1-beta/customers/cus-acme/entities/org-acme" \
-H "X-API-KEY: "
```
### Archiving and unarchiving entities
Archiving is a soft-delete: the entity disappears from the list but remains accessible via GET-by-ID.
```typescript TypeScript theme={null}
// 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'] });
```
```bash curl theme={null}
# Archive
curl -X POST https://api.stigg.io/api/v1-beta/customers/cus-acme/entities/archive \
-H "X-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.
```typescript TypeScript theme={null}
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' },
],
});
```
```bash curl theme={null}
curl -X PUT https://api.stigg.io/api/v1-beta/customers/cus-acme/assignments \
-H "X-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`):
```json theme={null}
[
{
"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.
```typescript TypeScript theme={null}
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
```typescript TypeScript theme={null}
// 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);
}
```
```bash curl theme={null}
curl "https://api.stigg.io/api/v1-beta/customers/cus-acme/assignments?entityId=team-eng" \
-H "X-API-KEY: "
```
## What's next
Gate access before consumption and record usage after
Fetch usage and budget data for dashboards and admin UIs