Glossary

Definitions of key terms used throughout Stategraph.

Terms

Tenant

An organizational boundary in Stategraph. All states, transactions, and users belong to a tenant. A tenant is similar to a team or organization — it keeps resources isolated between groups.

Every API operation that creates or queries states requires a tenant ID.

State

A Terraform state file tracked by Stategraph. Each state belongs to a tenant and is uniquely identified by the combination of its group ID and workspace. States contain the resource inventory that Terraform uses to map real infrastructure to configuration.

Group ID

A UUID that identifies a state in the Terraform HTTP backend URL. Multiple workspaces can share the same group ID — Stategraph uses the pair of group_id + workspace to locate the correct state.

The group ID appears in the backend URL that Terraform uses:

http://<host>/api/v1/states/backend/<group_id>

Workspace

Maps to Terraform workspaces. Defaults to "default" if not specified. Multiple workspaces can share the same group ID, allowing you to manage environment variants (e.g., staging, production) under a single logical grouping.

State ID

An internal UUID that uniquely identifies a state record. Used in API calls such as listing resource instances or viewing state details. This is distinct from the group ID — the state ID is Stategraph's primary key, while the group ID is used for Terraform backend routing.

Transaction

A recorded change to state. Each terraform apply that modifies state creates a transaction. Transactions provide an audit trail of infrastructure changes, including who made the change and when. Transactions can be tagged with metadata and have a lifecycle: open, completed, or aborted.

Orphaned Candidate

A Terraform resource flagged by Stategraph's graph analysis as potentially unused. A resource is considered an orphaned candidate when both of the following are true: (1) no other resource depends on it (leaf node), and (2) it is either outside any module or has at most one dependency. Resources inside a module with multiple dependencies are excluded because modules typically bundle related resources intentionally. Not every flagged resource is actually orphaned — review each one to decide whether to remove it or leave it in place.

API Key

A bearer token used to authenticate CLI, Terraform, and programmatic API requests. API keys are created in the Settings page of the Stategraph UI. For Terraform's HTTP backend, the API key is passed as the password in HTTP Basic Auth (with session as the username).

Mapping to Terraform and HCP Terraform