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

# Diagnose authentication and access errors

> Separate a missing key, insufficient permissions, workspace scope, and app actor access.

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](/environments/credentials) 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](/environments/access#revocation-and-app-access-have-different-effects) 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.


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