# Introduction

The Borkol storefront API is the public HTTP API of the Borkol commerce platform. It gives you programmatic, read and write access to a single store (a tenant): its product catalog, stock levels, customers, orders, and custom objects. You use it to build custom storefronts, headless frontends, mobile apps, and server-side integrations against a Borkol store.

The API is a conventional JSON-over-HTTPS API. Every request and response body is JSON. Authentication is a tenant API key sent as a bearer token. There are no cookies, no sessions, and no OAuth flows on the storefront API.

## Base URL

All requests go to:

```
https://api.borkol.com
```

The API is versioned in the URL path. The current and only version is `v1`, so every route in this documentation starts with `/v1`. Authenticated storefront routes live under `/v1/api/...`; the only unauthenticated route is the health check at `/v1/ping`.

Module surfaces mount under `/v1/api/{module}`:

| Module | Mount point |
| --- | --- |
| Commerce | `/v1/api/commerce` (plus `/v1/api/commerce/configurator`) |
| Stock | `/v1/api/stock` |
| Customers | `/v1/api/customers` |
| Objects | `/v1/api/objects` |

A module surface is only reachable when that module is enabled for your store. Calling a route of a disabled module returns `403 {"error": "Module not enabled: {key}"}`. See [Errors and rate limits](./errors-and-rate-limits) for the full error catalog.

## Authentication in one line

Every `/v1/api` request carries a tenant API key as a bearer token:

```
Authorization: Bearer {api_key}
```

The key identifies the store, so no other tenant header is needed. Merchants create keys in the client dashboard (app.borkol.com) under Settings > API keys. Each key carries a set of scopes (for example `commerce:read`) that control which endpoints it may call. The full details are on the [Authentication](./authentication) page.

## Conventions

These hold across the whole API:

- Resource IDs are UUID strings (API key IDs, which only appear in the merchant dashboard flow, are integers).
- Money values are integers in minor units (cents) with a separate ISO 4217 `currency` field. `15900` with `"currency": "EUR"` means EUR 159.00.
- Timestamps are ISO 8601 strings.
- List endpoints use the pagination envelope documented once in [Errors and rate limits](./errors-and-rate-limits). The fundamentals endpoints on these pages (`/v1/ping`, `/v1/api/me`) return bare JSON objects with no wrapper.

## Quickstart

Three requests take you from nothing to your first catalog call.

**Step 1: verify connectivity.** `/v1/ping` needs no credentials and confirms the base URL and API version are reachable.

```bash title="Request"
curl https://api.borkol.com/v1/ping
```

```json title="Response"
{
  "status": "ok",
  "version": "v1"
}
```

**Step 2: verify your API key.** Create a key in the client dashboard (Settings > API keys) with at least the `commerce:read` scope, then call `/v1/api/me`. It returns the store the key belongs to and the scopes the key carries. This endpoint requires no scope, only a valid key.

```bash title="Request"
curl https://api.borkol.com/v1/api/me \
  -H "Authorization: Bearer {api_key}"
```

```json title="Response"
{
  "tenant": {
    "id": "9c4e7f0a-2b31-4d6e-8f0a-1d2c3b4a5e6f",
    "name": "Example Store",
    "slug": "example-store"
  },
  "scopes": ["tenant:read", "commerce:read"]
}
```

**Step 3: fetch the catalog.** With a key that carries `commerce:read`, list products from the commerce module. This request fails with `403 {"error": "Module not enabled: commerce"}` if the commerce module is not enabled for the store, and with `403 {"message": "Invalid ability provided."}` if the key lacks the `commerce:read` scope.

```bash title="Request"
curl https://api.borkol.com/v1/api/commerce/products \
  -H "Authorization: Bearer {api_key}"
```

The response is a paginated product list; the product endpoints are documented in the Commerce chapter.

## Where to go next

- [Authentication](./authentication): API keys, scopes, the `/v1/api/me` endpoint, and tenant suspension.
- [Errors and rate limits](./errors-and-rate-limits): every error envelope, the 422 validation shape, rate limiting, and the pagination envelope.
- [Webhooks](/webhooks/index): event-driven notifications for orders and stock changes.