> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.voodoo.center/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.voodoo.center/_mcp/server.

# Quickstart

This is the fastest path from zero to a fulfilled order. You'll create an API
key, exchange it for an access token, place an order, and receive the terminal
result on your webhook. Every request goes to the single base URL:

**Base URL** — `https://api.voodoo.center` (HTTPS only). Auth endpoints live
under the same host at `/api/v1/auth`.

## Prerequisites

* A Voodoo Center account with a funded balance.
* Access to the dashboard **API** page (to create a key and set your webhook).
* An item to buy — you get its `item_id`, product type, quantity bounds and
  input fields from the **catalog export** (see [Placing orders](/orders)).

In the dashboard, open the **API** page and create a key. The raw key
(format `ak_...`) is shown **once**, at creation — copy it immediately and
store it as a secret. You can revoke and re-create keys here at any time.

On the same **API** page, set your **Webhook URL** (publicly reachable over
HTTPS) and copy the **signing secret** (`whsec_...`, also shown once). This
is where terminal order results are pushed. You can skip this and poll
instead, but the webhook is the lower-latency path.

Trade your `ak_` key for a short-lived Bearer token (valid **2 hours**):

```bash title="1 — Get an access token"
curl -X POST https://api.voodoo.center/api/v1/auth/token/client \
  -H "Content-Type: application/json" \
  -d '{"api_key":"ak_your_api_key_here"}'
```

```json title="Response"
{
  "access_token": "eyJhbGciOiJFZERTQSIsImtpZCI6Ii4uLiJ9...",
  "token_type": "Bearer"
}
```

Send `access_token` as `Authorization: Bearer <access_token>` on every
other request. Re-exchange the key when the token expires.

```bash title="2 — Confirm you can authenticate"
curl https://api.voodoo.center/api/v1/account/balance \
  -H "Authorization: Bearer <access_token>"
```

```json title="Response"
{ "balance": 1240.75 }
```

Buy a key item. `POST /api/v1/orders` charges your balance and returns `201`
immediately with `status: "pending"` — fulfillment runs in the background.

```bash title="3 — Place an order"
curl -X POST https://api.voodoo.center/api/v1/orders \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "item_id": 4090,
    "quantity": 2,
    "merchant_order_id": "po-10231"
  }'
```

```json title="201 Created"
{
  "id": "0190f8a1-6b2c-7e33-9a10-4c1d2e3f5a6b",
  "status": "pending",
  "merchant_order_id": "po-10231",
  "source": "api"
}
```

Always send a unique `merchant_order_id` — it makes retries idempotent.

When the order settles, Voodoo Center `POST`s a signed event to your webhook
URL. Verify the `X-Webhook-Signature` against the **raw** body, then read the
terminal `status`, delivered `codes` and any `refund_amount`:

```json title="Webhook — completed key order"
{
  "order_id": "0190f8a1-6b2c-7e33-9a10-4c1d2e3f5a6b",
  "merchant_order_id": "po-10231",
  "status": "completed",
  "delivered_quantity": 2,
  "refund_amount": 0,
  "codes": ["ABCD-1234-EFGH-5678", "IJKL-9012-MNOP-3456"]
}
```

Prefer not to run a webhook yet? Poll
`GET /api/v1/orders/{id}` until `status` is terminal instead.

## Try it without leaving the docs

The [API Reference](/api-reference) tab has a live **API Explorer** for every
endpoint. It's wired to obtain the access token for you — enter **only your
`ak_` API key** once, run any endpoint, and the Explorer fetches a fresh Bearer
token behind the scenes and attaches it automatically. You never paste a JWT.

The API-key → token flow in depth, plus token lifetime and refresh.

Item types, fields, quantity rules and the order lifecycle.

Verify signatures and handle retries idempotently.

The error envelope and create-time vs. async failures.