> ## 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.

# Workspaces, members, and API keys

> Understand organization membership, workspace scope, and the permissions that separate management from app access.

State Machines uses separate identities for people in your organization, programs that manage environments, and actors inside replica apps.

## Membership belongs to the organization

An organization represents your company. Each member has the role `owner`, `admin`, or `member`. A role grants a set of management permissions. To find out why an action was denied, read `sm.me().permissions`. In State Machines today, all three roles hold every permission. The roles differ only in who can change whom: nobody changes a member ranked above them, so only an owner changes an owner.

An invitation invites a person to join the organization. After accepting, the person can see every workspace in that organization. There is no separate workspace membership list. Workspaces group resources. They do not restrict one organization member to a private set of environments.

Member management requires a member session and the matching `members:read` or `members:write` permission. A person cannot change their own role, remove themselves, grant a role above their own, or change someone ranked above them. The organization must keep at least one owner.

## Workspace selection controls resource scope

A workspace groups environments, snapshots, and API keys inside the organization. The dashboard's workspace selector controls the workspace you are viewing. Switching the selector does not move resources or change an existing API key's scope.

For member access tokens, the SDK's `workspaceId` selects a workspace for calls that do not otherwise identify one. Resource IDs identify their own workspace on resource-specific calls. A workspace API key always remains bound to its workspace.

Archiving a workspace prevents new environments and snapshots, and changes to their metadata. Existing resources remain readable. Environment pause, resume, and deletion remain available with the required permissions. Archiving does not revoke API keys or delete environments.

## API keys identify programs

An API key belongs to one workspace. It can hold these permissions:

| Permission | Allows |
| - | - |
| `environments:read` | Read environments, recorded requests and bodies, and audit events. |
| `environments:write` | Create, update, pause, resume, and delete environments. |
| `environments:connect` | Obtain app credentials. |
| `snapshots:read` | Read snapshots and use them to create environments, with `environments:write`. |
| `snapshots:write` | Create, update, and delete snapshots. |

These permissions are separate. Write permission does not imply read or connect permission. A workflow that creates an environment, waits for it, and connects needs the permission for each operation. A key cannot receive permissions its creator does not hold.

API keys cannot manage members or invitations, create or modify workspaces, or list, create, or revoke API keys. Those operations require a member access token and the matching permission. Passing a workspace ID or more permission names does not make a key a member session.

The dashboard's **Create API key** form requests the key-eligible permissions held by the signed-in member. To request a smaller set, use the member-authenticated management API.

Create a key in the workspace it needs and store its value when shown. The dashboard cannot show the complete value again. Replaying a successful key creation with the same idempotency key also returns metadata without the secret. If the value is lost, revoke that key and create a replacement.

The SDK reads `STATEMACHINES_API_KEY` by default in any runtime with a global `process`, such as Node.js. `sm.me()` returns the current principal, its permissions, its organization and role, the workspace an API key is bound to (null for a member), and the organization's limits. It never returns the secret.

## Revocation and app access have different effects

Revoking an API key prevents future management calls with that key. Environments created by that key continue until deleted or expired. Credentials already issued for their apps keep working. Delete the environment when its app data and access must end.

Removing a member revokes every API key that member created, in every workspace.

[Credentials and actors](/environments/credentials) describes actors, the identities inside an app.

[Access troubleshooting](/troubleshooting/access) separates missing authentication, insufficient permissions, and a resource outside the caller's workspace.


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