# 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:

```bash
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:

```bash
cd cod-client-astro
npm run seed:admin
npm run dev
```

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

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

<Stepper toc={false}>

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

</Stepper>

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

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

<Stepper toc={false}>

1. Open the dashboard and go to **Integrations**.
2. Open **Store API key**.
3. Reveal and copy the key.

</Stepper>

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

```http
X-Store-API-Key: your_store_api_key_here
```

:::warning
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

<CodeTabs>

```bash title="Merchant API"
curl http://localhost:8787/api/orders \
  -H "X-API-Key: $COD_API_KEY"
```

```bash title="Storefront API"
curl "http://localhost:8787/store/products?limit=5" \
  -H "X-Store-API-Key: $STORE_API_KEY"
```

</CodeTabs>

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

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

## Use the playground

The [API reference](/api) includes an interactive playground.

<Stepper toc={false}>

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

</Stepper>

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](/authentication) for the full auth model and scope rules.
- Read [Errors](/errors) before writing retry logic.
- Use [Webhooks](/webhooks) to receive your store's events on your own server, and read [Carrier webhooks](/carrier-webhooks) for how carriers report deliveries.
- Connect an AI client through the [MCP server](/mcp).