> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usestatemachines.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Resources and how they relate

> How organizations, workspaces, apps, actors, environments, and snapshots relate to one another.

An environment is the unit you create for a task. It contains named apps and their data. The other resources decide who can use that environment, what it runs, and which data it starts with.

## A workspace scopes keys, not membership

An organization is your company. Its members sign in to the dashboard. A workspace groups environments, snapshots, and API keys within that organization.

A workspace API key limits a program to that workspace and the permissions on the key. Members belong to the organization and can see all of its workspaces. Two teams in different workspaces still share one membership. The [access guide](/environments/access) explains the difference.

## An app name selects one copy of a fixed version

An app is a replica product, such as `salesforce`. A version is a fixed build of that app. A fresh environment runs the app's default version. A snapshot keeps the versions and settings of its source apps.

The app's name identifies one copy inside an environment. A short declaration such as `apps: ['salesforce']` also uses `salesforce` as that name. If your task needs two Salesforce copies, give them different names and connect by name. Each copy keeps its own data. See [creating named apps](/environments/create).

Settings configure the app when it starts. Records you write through its API are app data, not settings. Each replica decides which settings it accepts. The settings object does not let you set arbitrary vendor configuration.

## Members manage environments, actors make app requests

A member is a person in your State Machines organization. An actor is an identity inside a replica app.

Management permissions decide whether a member or API key can create, inspect, connect to, or delete an environment. After you connect, the selected actor is the identity of native app requests. A Salesforce administrator actor has no permission to manage State Machines workspaces.

Discover the available actors from the environment's app version. Use the returned actor ID, not a role label or a State Machines member ID. [Credentials and actors](/environments/credentials) explains the request headers and login information.

## A snapshot copies data into new environments

An environment starts, runs, can pause, and ends deleted. Its status is `starting`, `running`, `paused`, `failed`, or `deleted`. A snapshot saves prepared app data for later environment creation.

Restoring a snapshot creates independent apps and data. Writes to one restored environment do not change the snapshot or another restored environment. Use a snapshot when several tests need the same starting records.

Pausing keeps the environment and its data for a limited time. Creating a snapshot saves reusable starting data. Deleting the environment removes its app data. A ready snapshot is a separate resource and stays. [Lifecycle](/environments/lifecycle) and [snapshot reuse](/snapshots/reuse) describe the status and cleanup rules.

A State Machines snapshot is not an export of a customer's Salesforce organization. Its source is an existing State Machines environment.

## Requests and audit events record different things

A request records an HTTP call to a replica app. An audit event records a management action or lifecycle outcome, such as an accepted environment creation or an environment that started.

An accepted management action and a successful native app request prove different things. For example, `environment.created` does not prove that a later Salesforce insert succeeded. Use the native response and a read-back assertion for that. [Inspect requests and audit events](/environments/observability) explains what is recorded and what can be left out.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.