Skip to main content
First identify which endpoint failed. A management API key authenticates calls to State Machines. Credentials authenticate calls to an app. An API key does not work at an app URL, and app credentials do not work at the management API.

​
Check the management key

If construction throws Pass apiKey or set STATEMACHINES_API_KEY, check that the variable is present in the process that runs the code. The SDK does not load .env files. In Cloudflare Workers, pass apiKey explicitly. For an HTTP 401 with unauthenticated, check whether the key is missing, expired, or revoked. Replace it through the dashboard if needed. Do not print the key while diagnosing the failure. For 403 with forbidden, inspect the current permissions through sm.me() and identify the operation that failed. Creating an environment requires environments:write, waiting for its status requires environments:read, and obtaining app credentials requires environments:connect. If the failed call manages members, invitations, workspaces, or API keys, check the caller type. An API key gets 403 forbidden on these operations, even when it holds every environment permission. Sign in as a member with the required permission. API keys cannot create API keys. If a dashboard action is unavailable, check both permission and environment status. Copy prompt needs a running environment. Pause is available on running environments. Resume is available on paused or failed environments. Ask an organization administrator for missing management permissions.

​
Confirm the workspace

An API key belongs to one workspace. Changing the selected workspace in your browser does not change the key’s scope. A 404 with not_found can mean the resource is unavailable in the key’s workspace. Compare the resource’s workspace with the key’s workspace returned by sm.me(). For member access tokens, confirm the workspaceId passed to the SDK. Do not recreate data until you have checked that the original resource is in the expected workspace.

​
Check app credentials separately

For a request to the app URL, use the URL and headers returned by connect(). Credentials and actors lists the headers and actor authentication each API needs. If authentication succeeds but a Salesforce operation is denied, confirm the selected actor and its permissions. A State Machines organization role is not a Salesforce actor role. Revoking an API key does not end access to app data. See revocation and app access for what revocation ends and what it leaves running.

​
Recover dashboard access

If the dashboard shows a sign-in prompt, sign in again before retrying the action. If a workspace or resource link is unavailable, confirm the selected organization and workspace. A resource from another organization can appear missing even when its ID is correct. An archived workspace refuses new environments and snapshots, and changes to their names or labels. For workspace_archived, switch to an active workspace for a new resource or ask a member with workspaces:write to unarchive the original workspace. Existing environment pause, resume, and deletion remain available with the required permission. If a key was created but its value is no longer visible, revoke that key and create another. Refreshing the list or replaying creation cannot recover the secret.