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

# Credentials and actors

> Authenticate native app requests without sending your State Machines API key to the app.

`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

| Field | Purpose |
| - | - |
| `environmentId`, `app`, `actorId` | Identify the environment, named app, and actor these credentials belong to. |
| `url` | Base URL for this app in the environment. |
| `headers` | Environment authentication headers, normally `StateMachines-Environment-Token`. |
| `token` | Token for the actor inside the app. |
| `expiresAt` | The environment expiry at credential creation, represented as a `Date` in the SDK. |
| `login` | A nullable object with `authentication`, `url`, `parameters`, and `secrets` for the vendor login call. |
| `fetch(path, init?)` | SDK helper that calls a path under the app URL with the required credentials. |

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. Omitting `actorId` 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](/environments/create#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](/troubleshooting/requests).

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 for `running` 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.


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