Authentication and clients

The SDK authenticates with a PHPSandbox API key. Create one from API keys, copy it when it is shown, and store it in your application’s secret store.

PHPSANDBOX_TOKEN=your-api-key

API keys belong in trusted server-side code. Do not include one in a browser bundle, URL, log, sandbox file, or Git repository.

Create a client

Use the realtime client for terminals, streamed command output, file watching, and other live events:

import { PHPSandbox } from '@phpsandbox/sdk';

const token = process.env.PHPSANDBOX_TOKEN;
if (!token) throw new Error('PHPSANDBOX_TOKEN is required');

const client = PHPSandbox.realtime(token);

Use the REST client for request-and-response operations:

const client = PHPSandbox.rest(token);

Both clients can create and retrieve sandboxes. Choose the transport from the work the application needs to perform, not from the kind of sandbox it creates.

Rotate a key

Create a replacement key, update the application, verify that it can connect, and then revoke the old key. Use a separate key for each application and environment so one credential can be rotated without disrupting the others.

Revoking a key prevents new authenticated requests. Revoke exposed credentials immediately.

Handle failures

SDK failures are reported as RemoteError values with a code, status, message, source, and sometimes structured details. Handle a specific error only when the application can respond to it meaningfully:

import { RemoteError } from '@phpsandbox/sdk';

try {
  await client.notebook.get(sandboxId);
} catch (error) {
  if (RemoteError.is(error, 'NotFound')) {
    console.log('Sandbox not found');
    return;
  }

  throw error;
}

A 401 response usually means the key is missing or invalid. A 403 can mean the account no longer has an active Platform subscription or cannot perform the requested operation.