> ## Documentation Index
> Fetch the complete documentation index at: https://docs.archal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Call an environment

> Use returned provider URLs and scoped credentials with existing clients.

Wait for readiness, then read the connection for each selected environment.

```json theme={null}
{
  "status": "ready",
  "apiBaseUrl": "https://api.archal.ai/v1/sessions/.../environments/github/api",
  "mcpUrl": "https://api.archal.ai/v1/sessions/.../environments/github/mcp",
  "credentials": {
    "kind": "provider",
    "expiresAt": "2026-08-04T20:00:00.000Z",
    "headers": {
      "authorization": "Bearer <scoped-provider-credential>"
    }
  }
}
```

The exact header names vary by provider. Apply the returned
`credentials.headers` map instead of guessing a provider token shape.

## TypeScript client

```ts theme={null}
const response = await archal.callEnvironment(sandbox.sessionId, 'github', {
  method: 'POST',
  path: '/user/repos',
  body: { name: 'checkout-test', private: true },
});
```

The client strips caller-supplied provider authorization and applies the scoped
headers from the sandbox connection. It also prevents paths from escaping the
environment base URL.

## Existing provider clients

Configure the client's base URL with `apiBaseUrl`. Configure authentication
through the same seam your test account used, but supply the returned scoped
headers. Keep these credentials out of logs. Renewal can rotate them, so read
the renewed connection before continuing a long test.

## MCP

Use `mcpUrl` when it is not `null`. Provider tools remain in that environment's
own MCP surface. The Archal lifecycle MCP server intentionally does not merge
every provider tool into one namespace.

<Warning>
  Never send the Archal workspace key to an environment URL. The workspace key manages sandboxes.
  The environment data plane accepts only its returned, short-lived provider credential.
</Warning>