Authentication

Create an API key

Create keys in the console. A key is displayed once. Store it in your service’s secret manager and send it in the Authorization: Bearer header on authenticated Platform requests.

export SANDPI_API_TOKEN="your-platform-token"

curl \
    "https://api.sandpi.ai/v1/environments" \
    -H "Authorization: Bearer $SANDPI_API_TOKEN"

{
  "data": [
    {
      "id": "",
      "name": "",
      "status": "ready",
      "platform": {
        "initialCheckpointStatus": "pending",
        "workspaceRevision": -9007199254740991
      },
      "labels": {},
      "labelsRevision": 0,
      "networkPolicy": {
        "mode": "allow-all",
        "domainExceptions": [
          "example"
        ]
      }
    }
  ]
}

{
  "error": {
    "code": "platform_balance_insufficient",
    "message": "Top up Platform credits before submitting a Run.",
    "requestId": "req_example"
  }
}

The public API uses Platform tokens. The console uses a browser login and internal cookie-authenticated routes; your server-to-server client does not need a browser cookie. Your Platform token authenticates requests to Sandpi. Separately, supply your own model API key and compatible provider or gateway base URL in the Session connection. Sandpi encrypts that connection; model requests go directly from the Sandbox to your endpoint.

Personal and Project scope

A personal key accesses its account’s personal resources. A Project key accesses one immutable Team Project scope. Use the same scope for Environment creation and all its subsequent operations. Resource paths do not need a separate Project parameter.

Resource IDs must also belong to the named parent Environment and Session. Inaccessible resources can return 404, so check key scope and parent IDs as well as whether a resource exists.

Public and trigger-authenticated operations

Webhook management uses your Platform token, but inbound event receivers use the trigger’s secret and selected authentication protocol. A webhook secret is separate from a Platform API key. See custom webhook authentication.

The API documentation shows each operation’s authentication requirements from the contract.

Rotate and revoke

Create a replacement key, update your integration, verify it can read the intended resources, then revoke the previous key in the console. Removing a Team member does not revoke existing Project keys; revoke them separately. Token revocation prevents new authenticated requests; it is not a Run stop operation. Use stop and rollback to control admitted work.