env.connect(appName, { actorId? }) returns credentials for one app in an environment. The app name is the name assigned at creation, which defaults to the app ID.
Credential fields
Credentials contain secrets. State Machines does not store the returned credentials. Never log tokens, headers, or URLs that contain a token.
Actors
An actor is a predefined identity inside the app. OmittingactorId uses the app’s default actor. Salesforce’s default is its administrator.
The app’s version declares the available actors. sm.apps.versions(appId) returns them. A Salesforce actor ID is a Salesforce user ID, not a role name. Choose an actor shows how to find the actors of the version an environment runs.
Actor permissions govern native app operations. State Machines workspace permissions separately govern environment management and the ability to request credentials.
Request behavior
credentials.fetch() adds the environment headers and selects actor authentication for the matching API path. Salesforce REST and Bulk 2.0 use Authorization: Bearer. credentials.fetch() does not authenticate SOAP calls. Put credentials.token in SessionHeader/sessionId in the envelope yourself.
The helper never adds your State Machines API key. It does not follow redirects or retry requests. Caller-provided headers cannot replace environment authentication or the selected actor header. A leading slash resolves against the app root.
The helper returns HTTP error responses without throwing a management error. A network failure can still reject the call. Check response.ok and inspect the matching error format.
When an environment is created with tokenInUrl: true, the URL carries the environment token and headers is empty. Treat that URL as a secret. A separate vendor client must send credentials only to this app URL and disable redirects.
Credential lifetime and failures
Requesting credentials does not prove readiness. The API issues credentials for a starting, paused, or failed environment. It refuses deleted environments. Wait forrunning before native app calls. Pausing or deleting the environment makes app requests fail even when a caller still holds the credential object. After resume, request credentials again and use the current returned URL and expiry.
connect() requests credentials and reads the matching version’s API definitions. A metadata-read failure can reject connect() even when the credential request succeeded. The SDK caches successful API definitions per version on the client. It does not cache credential objects.
The fetch helper reaches only paths under the returned app URL. It rejects a path that escapes the app URL, including another origin, protocol-relative paths, and encoded traversal. It throws TypeError before sending those requests. Supply a vendor path such as /services/data/v67.0/limits, not a replacement gateway URL.
Native requests accept standard RequestInit, including signal, method, body, and headers. They do not use the client’s attemptTimeoutMs. Pass a signal when your integration needs a deadline. The SDK uses a custom constructor fetch implementation for both management and native calls, so that implementation must not attach the management key to every request.