Call an environment

Use returned provider URLs and scoped credentials with existing clients.

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

{
  "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

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.

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.