Getting started

This guide takes you from a local Wocart server to an authenticated request. If you already have a deployed instance, skip the local setup and use its API origin instead.

Base URLs

Environment	Base URL	Notes
Local	`http://localhost:8787`	`wrangler dev` in `cod-server`
Production	`https://api.codflow.store`	The public Wocart API (the host keeps Wocart's former name)

Every merchant endpoint is under /api/*. Storefront endpoints are under /store/*, and carrier callbacks are under /webhooks/*.

Run the API locally

From the repository root:

Code
npm ci
cd cod-server
npm run db:setup:local
npm run dev

The server starts on http://localhost:8787. In a second terminal, bootstrap the dashboard admin and start the dashboard:

Code
cd cod-client-astro
npm run seed:admin
npm run dev

The dashboard runs on http://localhost:4321.

Local D1 state is shared through .wrangler-shared. If sign-in fails on a fresh checkout, run npm run db:setup:local before npm run seed:admin.

Get an API key

Wocart has two kinds of keys, and they are not interchangeable.

Merchant API key

Use a merchant key for /api/*. It belongs to a dashboard user and inherits that user's role and scopes.

Open the dashboard and go to Team.
Generate a key for a team member, or rotate an existing key.
Copy the key when it is shown. It is not displayed again.

Send it in the X-API-Key header:

Code
X-API-Key: cod_your_api_key_here

An administrator can use every scope. A staff user can use only the tools and endpoints allowed by their assigned scopes.

Storefront API key

Use a store key for /store/*. It identifies the store to the public storefront API.

Open the dashboard and go to Integrations.
Open Store API key.
Reveal and copy the key.

Send it in the X-Store-API-Key header:

Code
X-Store-API-Key: your_store_api_key_here

A merchant key can read and change store data. Keep it on the server, in a secret manager or a Worker secret. Never put it in a storefront bundle, a browser app or a git repository.

Make your first request

curl http://localhost:8787/api/orders \
  -H "X-API-Key: $COD_API_KEY"

A successful list response has a data array and a count; a storefront product list also carries total, the size of the whole listing:

Code
{
  "success": true,
  "data": [],
  "count": 0
}

Use the playground

The API reference includes an interactive playground.

Choose Local development in the server selector (or Production for a deployed instance).
Click Authorize and paste the key for the scheme you are testing: X-API-Key or X-Store-API-Key.
Open an operation, fill in the parameters and send the request.

In local development the server echoes the request origin, so this docs site at http://localhost:3000 can call it directly.

Next steps

Read Authentication for the full auth model and scope rules.
Read Errors before writing retry logic.
Use Webhooks to receive your store's events on your own server, and read Carrier webhooks for how carriers report deliveries.
Connect an AI client through the MCP server.

Introduction Authentication