Egress credentials

Choose outbound access

Platform Environments support outbound service credentials through Sandbox0's network injection. The authored platform-openapi.json and generated API details cover creation, list/detail, configuration replacement, material rotation and deletion, with request examples. Supported projections are HTTP headers, request placeholder substitution, mTLS, username/password and SSH proxy. These credentials are separate from your Session model API keys.

Outbound restrictions

Credential injection authenticates matching outbound requests; it is not a destination allowlist. A credential's domains, ports and fail-closed policy restrict that credential rule, not all Environment traffic.

Configure the Environment's base network policy through the API or console. In block-all, enabled egress credentials with a current source version also allow their configured destinations and ports. Removing all base domain exceptions therefore does not block these credential destinations. Do not assume that omitting credentials blocks network access.

Credential rules do not merge. When enabled rules overlap for the same domain, port and protocol, only the first matching credential is injected. Sandpi orders rules by credential creation time, then credential ID; editing a credential does not move it ahead of an older rule. Keep all HTTP headers needed for one service in a single credential projection, or use destinations that do not overlap. The Platform API does not expose Sandbox0's request-level httpMatch selector.

Scope and secret material

Use a personal token for a personal Environment, or a token for its owning Project. Cross-owner, cross-Project and personal-to-Project access returns 404 before any credential source access. Secret material goes directly to Sandbox0; Sandpi stores only configuration and observed version/status. Reads never return material or the internal source reference. Do not put secrets in projection templates; refer to material variables instead.

Update credentials during execution

Mutations take the Environment lifecycle lock and require its state to be ready. They also work while its Sandbox is paused. An active Run or checkpoint can delay credential mutations while holding the lifecycle lock. After they acquire the lock and apply, rotation and policy edits affect subsequent outbound connections; established connections are not retroactively reauthenticated. Resolver kind is immutable. Disabling a credential retains its source; deleting it removes both the binding and source. Failed operations retain reconciliation state, so inspect the list before retrying creation after an ambiguous failure. Creating the same display name twice returns a conflict rather than allocating another source.

Fork and rollback behavior

Credentials are Environment configuration outside RootFS checkpoints. Rollback does not restore an earlier credential version. Forks start without credential records or bindings; configure the child explicitly. Environment deletion removes the Sandbox before deleting its credential sources. The existing TUI credential routes remain unavailable for Platform Environments.

curl -X POST \
    "https://api.sandpi.ai/v1/environments/$ENVIRONMENT_ID/egress-credentials" \
    -H "Authorization: Bearer $SANDPI_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
  "name": "GitHub API",
  "resolverKind": "static_headers",
  "projection": {
    "type": "http_headers",
    "headers": [
      {
        "name": "Authorization",
        "valueTemplate": "Bearer {{ .token }}"
      }
    ]
  },
  "rule": {
    "protocol": "https",
    "domains": [
      "api.github.com"
    ],
    "ports": [
      {
        "port": 443
      }
    ],
    "failurePolicy": "fail-closed"
  },
  "enabled": true,
  "material": {
    "type": "static_headers",
    "values": {
      "token": "YOUR_GITHUB_TOKEN"
    }
  }
}'

{
  "name": "GitHub API",
  "resolverKind": "static_headers",
  "projection": {
    "type": "http_headers",
    "headers": [
      {
        "name": "Authorization",
        "valueTemplate": "Bearer {{ .token }}"
      }
    ]
  },
  "rule": {
    "protocol": "https",
    "domains": [
      "api.github.com"
    ],
    "ports": [
      {
        "port": 443
      }
    ],
    "failurePolicy": "fail-closed"
  },
  "enabled": true,
  "material": {
    "type": "static_headers",
    "values": {
      "token": "YOUR_GITHUB_TOKEN"
    }
  }
}

{
  "data": {
    "name": "example",
    "resolverKind": "static_headers",
    "projection": {
      "type": "http_headers",
      "headers": [
        {
          "name": "example",
          "valueTemplate": "example"
        }
      ]
    },
    "rule": {
      "protocol": "http",
      "domains": [
        "example"
      ],
      "ports": [
        {
          "port": 1
        }
      ]
    },
    "enabled": false,
    "id": "example",
    "environmentId": "example",
    "status": "provisioning",
    "createdAt": 0,
    "updatedAt": 0
  }
}

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

Verify and rotate

Inspect the credential’s observed status before testing a new outbound connection. Replace material using the rotation operation, and check status again. Established connections can continue with their earlier authentication; reconnect to exercise the new version.

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

{
  "data": [
    {
      "name": "example",
      "resolverKind": "static_headers",
      "projection": {
        "type": "http_headers",
        "headers": [
          {
            "name": "example",
            "valueTemplate": "example"
          }
        ]
      },
      "rule": {
        "protocol": "http",
        "domains": [
          "example"
        ],
        "ports": [
          {
            "port": 1
          }
        ]
      },
      "enabled": false,
      "id": "example",
      "environmentId": "example",
      "status": "provisioning",
      "createdAt": 0,
      "updatedAt": 0
    }
  ]
}

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

curl -X PUT \
    "https://api.sandpi.ai/v1/environments/$ENVIRONMENT_ID/egress-credentials/$CREDENTIAL_ID/material" \
    -H "Authorization: Bearer $SANDPI_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
  "resolverKind": "static_headers",
  "material": {
    "type": "static_headers",
    "values": {
      "token": "YOUR_NEW_GITHUB_TOKEN"
    }
  }
}'

{
  "resolverKind": "static_headers",
  "material": {
    "type": "static_headers",
    "values": {
      "token": "YOUR_NEW_GITHUB_TOKEN"
    }
  }
}

{
  "data": {
    "name": "example",
    "resolverKind": "static_headers",
    "projection": {
      "type": "http_headers",
      "headers": [
        {
          "name": "example",
          "valueTemplate": "example"
        }
      ]
    },
    "rule": {
      "protocol": "http",
      "domains": [
        "example"
      ],
      "ports": [
        {
          "port": 1
        }
      ]
    },
    "enabled": false,
    "id": "example",
    "environmentId": "example",
    "status": "provisioning",
    "createdAt": 0,
    "updatedAt": 0
  }
}

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

Inbound versus outbound credentials

These credentials let an agent call a third-party service. They do not authenticate events sent to Sandpi. A Parseable webhook password authenticates incoming alerts; configure separate egress access or MCP tools if the agent also needs to query logs. See inbound webhooks.

Read and replace a binding

Read configuration and observed status, then replace the non-secret connection rules or projection. Secret changes use the separate material rotation operation.

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

{
  "data": {
    "name": "example",
    "resolverKind": "static_headers",
    "projection": {
      "type": "http_headers",
      "headers": [
        {
          "name": "example",
          "valueTemplate": "example"
        }
      ]
    },
    "rule": {
      "protocol": "http",
      "domains": [
        "example"
      ],
      "ports": [
        {
          "port": 1
        }
      ]
    },
    "enabled": false,
    "id": "example",
    "environmentId": "example",
    "status": "provisioning",
    "createdAt": 0,
    "updatedAt": 0
  }
}

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

curl -X PUT \
    "https://api.sandpi.ai/v1/environments/$ENVIRONMENT_ID/egress-credentials/$CREDENTIAL_ID" \
    -H "Authorization: Bearer $SANDPI_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
  "name": "GitHub API",
  "resolverKind": "static_headers",
  "projection": {
    "type": "http_headers",
    "headers": [
      {
        "name": "Authorization",
        "valueTemplate": "Bearer {{ .token }}"
      }
    ]
  },
  "rule": {
    "protocol": "https",
    "domains": [
      "api.github.com"
    ],
    "ports": [
      {
        "port": 443
      }
    ],
    "failurePolicy": "fail-closed"
  },
  "enabled": true
}'

{
  "name": "GitHub API",
  "resolverKind": "static_headers",
  "projection": {
    "type": "http_headers",
    "headers": [
      {
        "name": "Authorization",
        "valueTemplate": "Bearer {{ .token }}"
      }
    ]
  },
  "rule": {
    "protocol": "https",
    "domains": [
      "api.github.com"
    ],
    "ports": [
      {
        "port": 443
      }
    ],
    "failurePolicy": "fail-closed"
  },
  "enabled": true
}

{
  "data": {
    "name": "example",
    "resolverKind": "static_headers",
    "projection": {
      "type": "http_headers",
      "headers": [
        {
          "name": "example",
          "valueTemplate": "example"
        }
      ]
    },
    "rule": {
      "protocol": "http",
      "domains": [
        "example"
      ],
      "ports": [
        {
          "port": 1
        }
      ]
    },
    "enabled": false,
    "id": "example",
    "environmentId": "example",
    "status": "provisioning",
    "createdAt": 0,
    "updatedAt": 0
  }
}

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

Delete a credential

Deletion removes the binding and its source. It does not reauthenticate already established connections.

curl -X DELETE \
    "https://api.sandpi.ai/v1/environments/$ENVIRONMENT_ID/egress-credentials/$CREDENTIAL_ID" \
    -H "Authorization: Bearer $SANDPI_API_TOKEN"

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