Integrations

An integration lets PHPSandbox use an external provider on behalf of your account. It stores the provider authorization separately from sandbox files and secrets.

The SDK currently supports token-based integrations for GitHub, Cloudflare, and Laravel Cloud.

Link an integration

Link provider credentials from trusted server-side code:

const github = await client.integrations.link({
  provider: 'github',
  label: 'Product repository',
  authorization: {
    type: 'token',
    token: process.env.GITHUB_TOKEN!,
  },
});

PHPSandbox stores the token but does not return it in the response. Linking succeeds when the credential is stored; the provider validates it when an operation uses it.

Attach it to a sandbox

const github = await client.integrations.get('integration-id');

const binding = await sandbox.integrations.attach({
  integration: github,
});

Attaching an integration selects the authorization that this sandbox will use for that provider. It does not synchronize a repository, publish the sandbox, or copy the token into its files.

A sandbox can have one attached integration for each provider. Replace the selection with binding.update():

Use binding.update() to replace the selected integration.

List and retrieve integrations

const integrations = await client.integrations.list();
const integration = await client.integrations.get('integration-id');

Store the integration ID when your application needs to select the same authorization in another process.

Update or unlink an integration

const github = await client.integrations.get('integration-id');

await github.update({ label: 'Production repository' });
await github.unlink();

Unlinking removes the stored authorization. It does not delete provider resources or sandbox files. Operations that depended on it will fail until the sandbox is attached to another active integration.

Give every provider token only the permissions required by the operation that will use it. Never collect or link provider tokens in untrusted browser code.