Quickstart | Voodoo Center | API Documentation

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).

Create an API key

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.

Set your webhook (recommended)

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.

Exchange the key for an access token

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

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"}'

Response

1 {
2   "access_token": "eyJhbGciOiJFZERTQSIsImtpZCI6Ii4uLiJ9...",
3   "token_type": "Bearer"
4 }

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

Check your balance (optional sanity check)

2 — Confirm you can authenticate

$ curl https://api.voodoo.center/api/v1/account/balance \
>   -H "Authorization: Bearer <access_token>"

Response

1 { "balance": 1240.75 }

Place your first order

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

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"
>   }'

201 Created

1 {
2   "id": "0190f8a1-6b2c-7e33-9a10-4c1d2e3f5a6b",
3   "status": "pending",
4   "merchant_order_id": "po-10231",
5   "source": "api"
6 }

Always send a unique merchant_order_id — it makes retries idempotent.

Receive the result on your webhook

When the order settles, Voodoo Center POSTs 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:

Webhook — completed key order

1 {
2   "order_id": "0190f8a1-6b2c-7e33-9a10-4c1d2e3f5a6b",
3   "merchant_order_id": "po-10231",
4   "status": "completed",
5   "delivered_quantity": 2,
6   "refund_amount": 0,
7   "codes": ["ABCD-1234-EFGH-5678", "IJKL-9012-MNOP-3456"]
8 }

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 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.

Authentication

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

Placing orders

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

Webhooks

Verify signatures and handle retries idempotently.

Errors

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