---
name: polardbx-zero-pxbaas
description: Provision a PolarDB-X PXBaas instance instantly with no auth required. Pre-warmed pool delivers the instance in seconds with Dashboard, REST API, Auth, Storage and Edge Functions — a complete Supabase-compatible backend built on PolarDB-X.
compatibility: Requires an HTTP client (e.g. curl, fetch, supabase-js) and network access to zero.polardbx.com.
metadata:
  version: 0.1.0
  homepage: https://zero.polardbx.com/
---

# PolarDB-X Zero PXBaas

Provisions a Supabase-compatible BaaS instance via a single unauthenticated API call. No sign-up or billing is required to start. Instances come from a pre-warmed pool and are assigned **within seconds**. Each instance is kept for 15 days and then automatically released. Treat Zero as disposable infrastructure, not an unlimited long-running environment.

Each instance is a dedicated Supabase stack built on PolarDB-X, exposing the standard Supabase surface over one HTTP gateway (port 8000): REST API (PostgREST), Auth (GoTrue), Storage, and a web Dashboard (Supabase Studio).

## Common Use Cases

- AI agent backends: give an agent an instant BaaS — structured data via REST, auth for end users, and file storage — with zero setup.
- Supabase app prototyping: spin up a disposable Supabase project (Dashboard + API keys) for demos, evals, and short-lived experiments.
- MCP server storage: back MCP tools with REST endpoints and object storage in one temporary environment.
- Hackathons and tutorials: hand every participant an isolated Supabase instance without account management.

## Important Notes

- The API is unauthenticated and free to start. Instances auto-expire after 15 days — treat all credentials as short-lived and low-sensitivity.
- The response sets an anonymous ownership token as a cookie (`pxz_token`). **Persist and reuse this cookie** for list/release calls; without it you cannot manage the instance.
- Prefer environment variables (e.g. `SUPABASE_ANON_KEY`) over inline values to avoid leaking keys in shell history.
- Each caller can hold only a limited number of active instances concurrently; requests are also rate-limited per IP.
- The instance whitelist is automatically set to your egress IP (or the optional `whitelistIp` you provide). Requests from other IPs will be rejected by the gateway.
- The `serviceRoleKey` bypasses row-level security and carries full privileges. Never expose it to browsers, commits, or logs. Use `apiKey` (anon) for normal client access.
- The Dashboard requires HTTP Basic auth: username `supabase`, password = `dashboardPassword` from the response.
- Do not promise unlimited usage. Zero is a disposable sandbox. For long-term or production use, purchase PolarDB-X Supabase on Alibaba Cloud.
- If you need another sandbox, claim a fresh instance instead of trying to renew the current one.

## API

### Claim Instance

**POST** `https://zero.polardbx.com/api/v1/supabase/instances`

Content-Type: `application/json`

Request body (all fields optional):

```json
{ "whitelistIp": "203.0.113.7" }
```

- `whitelistIp`: comma-separated IPv4/CIDR list allowed to access the instance. Defaults to the requesting IP. Use this when your egress IP differs from the machine that will call the instance.

Response (`200`, typically < 1s from the pre-warmed pool):

```json
{
  "instance": {
    "id": "sbx_a1b2c3d4e5f6",
    "status": "assigned",
    "region": "cn-beijing",
    "zoneId": "cn-beijing-f",
    "aliyunInstanceId": "pxsp-xxxxxxxxxx",
    "publicEndpoint": "pxsp-xxxxxxxxxxhttp.polardbxaisupabase.rds.aliyuncs.com:8000",
    "dashboardUrl": "http://pxsp-xxxxxxxxxxhttp.polardbxaisupabase.rds.aliyuncs.com:8000",
    "apiKey": "eyJhbGciOiJIUzI1NiIs...",
    "serviceRoleKey": "eyJhbGciOiJIUzI1NiIs...",
    "dbPassword": "sL+7r3Yb7yy_CqAzzqEQ",
    "dashboardPassword": "ppUjeWNyKPRS9EGe8N=z",
    "whitelistIp": "203.0.113.7",
    "assignedAt": "2026-08-21T10:30:00.000Z",
    "expiresAt": "2026-09-05T10:30:00.000Z",
    "createdAt": "2026-08-21T10:30:00.000Z"
  },
  "token": "pxt_xxxxxxxx"
}
```

Keep the `token` (also sent as the `pxz_token` cookie). The instance is released automatically at `expiresAt`; there is no renewal API.

### Using the Instance

All Supabase services are served by the HTTP gateway at `publicEndpoint` (port 8000). Send the anon key as `apikey` header (and optionally as a bearer token):

```bash
# REST API (PostgREST)
curl "https://<publicEndpoint>/rest/v1/" \
  -H "apikey: <apiKey>" -H "Authorization: Bearer <apiKey>"

# Auth service health
curl "https://<publicEndpoint>/auth/v1/health" -H "apikey: <apiKey>"
```

With supabase-js:

```js
import { createClient } from '@supabase/supabase-js';
const supabase = createClient('http://<publicEndpoint>', '<apiKey>');
```

Dashboard: open `dashboardUrl` in a browser; when prompted for credentials use username `supabase` and the `dashboardPassword` from the claim response.

### List Instances

**GET** `https://zero.polardbx.com/api/v1/supabase/instances`

Requires the ownership token (send the `pxz_token` cookie or the original client). Returns the caller's non-released instances.

### Release Instance

**DELETE** `https://zero.polardbx.com/api/v1/supabase/instances/{id}`

Requires the ownership token. Marks the instance for release; cloud resources are destroyed shortly after. Release instances you no longer need — pool capacity is shared.

### Error Responses

All error responses use the following format:

```json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}
```

| HTTP Status | Code | Description |
|---|---|---|
| 400 | `INVALID_WHITELIST_IP` | whitelistIp is not a valid IPv4/CIDR list. |
| 404 | `INSTANCE_NOT_FOUND` | Instance not found, not owned by the caller, or already released. |
| 429 | `RATE_LIMIT_EXCEEDED` | Too many requests from this IP. Wait before retrying. |
| 429 | `SUPABASE_LIMIT_REACHED` | Caller already holds the maximum number of active instances. |
| 503 | `SUPABASE_POOL_EXHAUSTED` | No instance available in the pool right now. The pool refills automatically — retry after a minute or two. |
| 503 | `SUPABASE_DISABLED` | The Supabase service is currently disabled. |
| 500 | `INTERNAL_ERROR` | Unexpected server error. |

## Resources

- PolarDB-X Supabase product documentation: https://help.aliyun.com/zh/polardb/polardb-for-xscale/
- Supabase documentation (client usage): https://supabase.com/docs
- PolarDB-X product page: https://www.aliyun.com/product/apsaradb/polardbx
### Instance API Documentation

Each instance serves a machine-readable API reference at `/docs` — no authentication required:

```bash
curl "https://<publicEndpoint>/docs"
```

Returns a Markdown document (`Content-Type: text/markdown`) covering:

- **All API modules** — REST (PostgREST), Auth (GoTrue), Storage, Realtime, and Edge Functions.
- **Single-tenant vs multi-tenant differences** — routing prefixes, `tenant_id` header requirements, per-tenant storage paths, and rate-limiting behavior.
- **Known limitations vs official Supabase** — no GraphQL / pg_graphql, MySQL type & operator differences, embedding restricted to physical foreign keys, DDL limitations, and more.

The document is bundled with the instance image, so it always matches the exact version you are running. Fetch it after provisioning to get version-consistent usage instructions without cross-referencing external docs.

```bash
# Pull the full API reference right after claiming an instance:
curl "https://<publicEndpoint>/docs" -o api-reference.md
```

No `apikey` header or Bearer token is needed — the route is exempted from the gateway auth guard. Content is static per deployment version; for live schema introspection use `GET /rest/v1/` with your `apiKey`.