Quickstart

This guide walks you from a fresh sandbox account to your first authenticated API call in under five minutes. By the end, you will have provisioned a workspace, generated a scoped API key, and triggered a webhook delivery you can verify locally. Every example below uses our public sandbox at api.spalce.dev — the same endpoints power production, just behind a stricter rate limit and a synthetic data fixture set.

1. Create a sandbox account

Sign up at dashboard.spalce.dev/signup. You will receive a verification email within thirty seconds. Once verified, the dashboard drops you into a fresh workspace with a single sandbox environment already provisioned. No credit card is required, and there is no usage charge for sandbox calls — only the global rate limit applies.

# Or create a workspace programmatically with the bootstrap CLI
npx @spalce/cli@latest init --name "Acme Sandbox" --region eu-west-1

2. Generate an API key

Navigate to Settings → API Keys and click Create key. Choose the read-write scope for this tutorial. Keys are shown exactly once — copy yours into a password manager or your local .env file before leaving the page. Keys are prefixed with sk_test_ in sandbox and sk_live_ in production so they are easy to spot in logs and pull requests.

export SPALCE_API_KEY="sk_test_4eC39HqLyjWDarjtT1zdp7dc"
export SPALCE_BASE_URL="https://api.spalce.dev/v1"

3. Make your first API call

Every endpoint accepts and returns JSON, uses standard HTTP status codes, and authenticates via a bearer token in the Authorization header. Let us create a Customer — the most fundamental resource in the platform — and read it back.

curl -X POST "$SPALCE_BASE_URL/customers" \
  -H "Authorization: Bearer $SPALCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Adwoa Mensah",
    "email": "[email protected]",
    "metadata": { "source": "quickstart" }
  }'

A successful response returns a 201 Created with the new resource. Note the cus_ prefix — every resource type has its own short prefix so they are unambiguous in logs and stack traces.

{
  "id": "cus_01HE7K8R9XGTQXJN3M2WVYBPD4",
  "object": "customer",
  "name": "Adwoa Mensah",
  "email": "[email protected]",
  "created": "2026-05-20T09:14:22Z",
  "livemode": false,
  "metadata": { "source": "quickstart" }
}

4. Receive your first webhook

The same Create call produces a customer.created event on the event bus. To see it locally, start the Spalce CLI tunnel — it forwards sandbox events to a port on your machine without you having to configure ngrok or a public hostname.

spalce listen --forward-to localhost:3000/webhooks/spalce

5. Verify the signature

Every webhook is signed with HMAC-SHA256 over the raw request body. Verify the signature before trusting any payload — and always use the raw body, not a re-serialized version, since whitespace matters.

import crypto from "node:crypto";

export function verifySpalceSignature(rawBody: string, header: string, secret: string) {
  const [t, v1] = header.split(",").map((p) => p.split("=")[1]);
  const signedPayload = `${t}.${rawBody}`;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(signedPayload)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

What to explore next

• Read Accounts & Environments to understand the production promotion flow.
• Skim Authentication if you need OAuth instead of static keys.
• Jump to API Overview for the full endpoint catalog.
• Check the Webhooks guide for retry behavior and event types.