---
title: How to create an API key and make your first request
updated: 2026-10-06
canonical: https://corekchat.com/ayuda/en/api-publica
---

The API lets another system read your orders, your menu, your reservations and
the status of your tables. To get in, that system uses a **key**: a long secret
that you create, with just the permissions it needs, and that you can revoke
whenever you want. The first part of this guide is for whoever manages the
account; the second, for whoever programs the connection.

## Step 1: open the API tab

Open «Configuraciones» (Settings) and choose «API», in the «Desarrolladores»
(Developers) group. There you see the keys that already exist, with their
permissions and the last time each one was used.

(Captura del sistema, sólo para clientes: The API section of Settings with an active key called Contabilidad)

## Step 2: create one key per system

Press «Nueva llave» (New key), give it a name that says who's going to use it
("Accounting", "Online store") and check **only** the permissions that system
needs:

| Permission | What it can read |
|---|---|
| Read orders | Orders with their products, status and total |
| Read products and menu | Products, prices, availability and categories |
| Read reservations | Reservations with their date, party size and status |
| Read tables and dining room status | Tables, which floor and zone they're on, and whether they're free or occupied (requires the POS module) |

It's best to have one key per system: if you ever have to revoke one, the other
integrations keep working.

(Captura del sistema, sólo para clientes: The new key form with the name and two permissions checked)

## Step 3: copy the key right then

When you press «Crear llave» (Create key), the full key appears **only once**.
Copy it and hand it to whoever programs the connection through a secure channel.
We only store a fingerprint of the key, so not even the CorekChat team can show
it to you again: if it's lost, you revoke it and create another one.

(Captura del sistema, sólo para clientes: The Copy the key now notice with the full key and the Copy button)

Treat it like a password: don't paste it into a group chat, a forwarded email or
a code repository.

## Revoking a key

«Revocar» (Revoke) makes it useless instantly: the next request with that key
gets rejected. Do it when you change providers, when someone who knew it leaves
the team or if you suspect it leaked. You can have up to ten active keys at a
time.

## For whoever programs it: how to make requests

All requests go to this base address, with the key in the `Authorization`
header:

```
https://corekchat.com/api/v1
Authorization: Bearer ck_live_...
```

A first test request, which returns the five most recent orders:

```bash
curl -H "Authorization: Bearer ck_live_YOUR_KEY" \
  "https://corekchat.com/api/v1/orders?limit=5"
```

### What you can query

| Request | Permission | Filters |
|---|---|---|
| `GET /orders` | Read orders | `status`, `from`, `to` (creation date), `limit`, `cursor` |
| `GET /orders/{id}` | Read orders | — |
| `GET /products` | Read products and menu | `available=true` or `false`, `limit`, `cursor` |
| `GET /products/{id}` | Read products and menu | — |
| `GET /reservations` | Read reservations | `status`, `from`, `to` (reservation date), `limit`, `cursor` |
| `GET /reservations/{id}` | Read reservations | — |
| `GET /tables` | Read tables | `branch_id`, `active=true` or `false`, `limit`, `cursor` |
| `GET /tables/{id}` | Read tables | — |

Dates use ISO 8601 format (`2026-09-27T00:00:00-05:00`). Amounts are in
Colombian pesos, without decimals.

### What responses look like

A list returns the results in `data` and says whether there are more:

```json
{
  "data": [
    {
      "id": "8f1c…",
      "status": "delivered",
      "channel": "whatsapp",
      "branch_id": "3a2e…",
      "customer_name": "Julián Pardo",
      "total": 42000,
      "currency": "COP",
      "items": [
        {
          "product_id": "b71d…",
          "name": "Hamburguesa La Esquina",
          "quantity": 2,
          "subtotal": 38000
        }
      ],
      "cancellation_reason": null,
      "created_at": "2026-09-27T13:05:12.000Z",
      "updated_at": "2026-09-27T13:40:02.000Z"
    }
  ],
  "has_more": true,
  "next_cursor": "8f1c…"
}
```

For the next page, repeat the request with `cursor=` set to the `next_cursor`
you received. Pagination is by cursor and not by page number on purpose: if
orders come in while you go through the list, rows are neither repeated nor
skipped. Each page returns 25 results by default and 100 at most (`limit`).

A table also includes its `status` — `available` (free), `occupied` or
`bill_requested` (asked for the bill) — and, if it's open, the `session` with
the time it was opened.

### Errors

Errors always have the same shape, with a stable `code` you can program
against:

```json
{ "error": { "code": "insufficient_scope", "message": "…" } }
```

| Status | `code` | What happened |
|---|---|---|
| 401 | `unauthorized` | The key is missing, mistyped, expired or revoked |
| 402 | — | The plan no longer includes the API, or the POS module is missing for tables (`module_not_purchased`) |
| 403 | `insufficient_scope` | The key doesn't have permission for that request |
| 404 | `not_found` | That order, product, reservation or table doesn't exist in your account |
| 429 | `rate_limited` | You went over the request limit; wait as long as the `Retry-After` header says |

### Request limit

Each key can make up to **120 requests per minute**. Responses include the
`x-ratelimit-limit`, `x-ratelimit-remaining` and `x-ratelimit-reset` headers so
the system knows how much it has left. If you need to know about each order
instantly, don't query the API every few seconds: use
[webhooks](/ayuda/en/webhooks), which notify you on their own.